Add getting started help to readme
This commit is contained in:
342
README.md
342
README.md
@@ -1,23 +1,25 @@
|
||||
# paige
|
||||
# Paige
|
||||
|
||||
A simple Hugo theme. [Try it out.](https://willfaught.com/paige)
|
||||
|
||||
## Screenshots
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/screenshot.jpg">
|
||||
|
||||
Home page:
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/home1.jpg">
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/home2.jpg">
|
||||
|
||||
Single page:
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/single.jpg">
|
||||
|
||||
List page:
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/list.jpg">
|
||||
|
||||
Single page:
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/single.jpg">
|
||||
|
||||
Taxonomy page:
|
||||
|
||||
<img src="https://github.com/willfaught/paige/raw/master/images/taxonomy.jpg">
|
||||
@@ -58,6 +60,254 @@ Search page:
|
||||
- Social links
|
||||
- Twitter sharing
|
||||
|
||||
Soon: Dark color scheme and dynamic color schemes, when Bootstrap 5.3 releases.
|
||||
|
||||
## Get started with Hugo
|
||||
|
||||
1. [Install Hugo](https://gohugo.io/installation/).
|
||||
|
||||
For Homebrew on Mac:
|
||||
|
||||
```sh
|
||||
$ brew install hugo
|
||||
```
|
||||
|
||||
2. Create a site:
|
||||
|
||||
```sh
|
||||
$ hugo new site yourproject
|
||||
```
|
||||
|
||||
3. Create a post:
|
||||
|
||||
```sh
|
||||
$ cd yourproject
|
||||
$ hugo new my-post.md
|
||||
```
|
||||
|
||||
See [Hugo's quick start guide](https://gohugo.io/getting-started/quick-start/) for more information.
|
||||
|
||||
## Install
|
||||
|
||||
### Option 1: Use a Hugo module
|
||||
|
||||
Example `config.yaml`:
|
||||
|
||||
```yaml
|
||||
module:
|
||||
imports:
|
||||
- path: "github.com/willfaught/paige"
|
||||
```
|
||||
|
||||
Install:
|
||||
|
||||
```sh
|
||||
$ hugo mod init github.com/youraccount/yourproject
|
||||
$ hugo mod get github.com/willfaught/paige
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```sh
|
||||
$ hugo mod get -u
|
||||
```
|
||||
|
||||
### Option 2: Use a Git submodule
|
||||
|
||||
Example `config.yaml`:
|
||||
|
||||
```yaml
|
||||
theme: "paige"
|
||||
```
|
||||
|
||||
Install:
|
||||
|
||||
```sh
|
||||
$ cd yourproject
|
||||
$ git submodule add https://github.com/willfaught/paige themes/paige
|
||||
$ git submodule update --init --recursive --remote
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```sh
|
||||
$ cd yourproject
|
||||
$ git submodule update --recursive --remote
|
||||
```
|
||||
|
||||
### Option 3: Use a copy
|
||||
|
||||
Example `config.yaml`:
|
||||
|
||||
```yaml
|
||||
theme: "paige"
|
||||
```
|
||||
|
||||
Install:
|
||||
|
||||
```sh
|
||||
$ cd yourproject
|
||||
$ git clone https://github.com/willfaught/paige themes/paige
|
||||
$ rm -rf themes/paige/.git
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```sh
|
||||
$ cd yourproject
|
||||
$ rm -rf themes/paige
|
||||
$ git clone https://github.com/willfaught/paige themes/paige
|
||||
$ rm -rf themes/paige/.git
|
||||
```
|
||||
|
||||
## Run
|
||||
|
||||
```sh
|
||||
$ hugo server -D
|
||||
```
|
||||
|
||||
## Configure
|
||||
|
||||
Optional site parameters:
|
||||
|
||||
```yaml
|
||||
math: true # Enable math typesetting with KaTeX
|
||||
paigebootstrapcss: "/my-assets/my-styles.css" # Use local Bootstrap styles
|
||||
paigebootstrapicons: "/my-assets/my-icons.css" # Use local Bootstrap icons
|
||||
paigebootstrapjs: "/my-assets/my-scripts.js" # Use local Bootstrap scripts
|
||||
paigedateformat: "2006 January 2" # Format for page dates
|
||||
paigehidethemecomment: true # Don't put a link to the project in a code comment
|
||||
paigehidethemelink: true # Don't put a link to the project in the footer
|
||||
```
|
||||
|
||||
If you set either `paigehidethemecomment` or `paigehidethemelink`, please credit this project in a post so others may find it.
|
||||
|
||||
Optional page parameters:
|
||||
|
||||
```yaml
|
||||
excludesearch: true # Don't include this page in search results
|
||||
link: "https://youtu.be/dQw4w9WgXcQ" # The reference for an anchor around the title
|
||||
math: true # Enable math typesetting with KaTeX
|
||||
```
|
||||
|
||||
Additional optional home page parameters:
|
||||
|
||||
```yaml
|
||||
blurb: "There's a new daddy in town." # Displayed below the greeting
|
||||
center: "my-center.jpg" # An image that is centered
|
||||
greeting: "You know best" # Displayed below the center and stretch images
|
||||
stretch: "my-stretch.jpg" # A 4x3 or panorama image that is stretched fully horizontally
|
||||
```
|
||||
|
||||
Additional optional list page parameters:
|
||||
|
||||
```yaml
|
||||
paigeshowfullpages: true # Show full page content in list pages
|
||||
```
|
||||
|
||||
Additional optional single page parameters:
|
||||
|
||||
```yaml
|
||||
excluderss: true # Don't include this page in RSS feeds
|
||||
```
|
||||
|
||||
Example `config.yaml`:
|
||||
|
||||
```yaml
|
||||
author:
|
||||
email: example@example.com
|
||||
name: Michael Bluth
|
||||
baseurl: https://example.com
|
||||
copyright: © Michael Bluth
|
||||
languagecode: en-us
|
||||
enablerobotstxt: true
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
unsafe: true
|
||||
highlight:
|
||||
style: vs
|
||||
menu:
|
||||
main:
|
||||
- identifier: home
|
||||
name: Home
|
||||
weight: 10
|
||||
url: /
|
||||
- identifier: about
|
||||
name: About
|
||||
weight: 20
|
||||
url: /about/
|
||||
- identifier: blog
|
||||
name: Blog
|
||||
weight: 30
|
||||
url: /blog/
|
||||
- identifier: categories
|
||||
name: Categories
|
||||
weight: 40
|
||||
url: /categories/
|
||||
- identifier: tags
|
||||
name: Tags
|
||||
weight: 50
|
||||
url: /tags/
|
||||
- identifier: search
|
||||
name: Search
|
||||
weight: 60
|
||||
url: /search/
|
||||
outputs:
|
||||
home:
|
||||
- html
|
||||
- json
|
||||
- rss
|
||||
paginate: 50
|
||||
permalinks:
|
||||
blog: /blog/:year/:month/:day/:title/
|
||||
social:
|
||||
envelope: mailto:example@example.com
|
||||
discord: https://discord.com/users/example
|
||||
github: https://github.com/example
|
||||
facebook: https://facebook.com/example
|
||||
instagram: https://instagram.com/example
|
||||
linkedin: https://www.linkedin.com/in/example
|
||||
reddit: https://reddit.com/u/example
|
||||
twitch: https://www.twitch.tv/example
|
||||
twitter: https://twitter.com/example
|
||||
youtube: https://www.youtube.com/user/example
|
||||
theme: paige
|
||||
timezone: America/Los_Angeles
|
||||
title: No Borders, No Limits
|
||||
titlecasestyle: Go
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
The `paige-search` layout provides full site search.
|
||||
|
||||
Example `config.yaml`:
|
||||
|
||||
```yaml
|
||||
outputs:
|
||||
home: ["html", "json", "rss"]
|
||||
```
|
||||
|
||||
Example `content/search.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: paige-search
|
||||
title: Search
|
||||
---
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
If `partials/paige-head-last.html` exists in the site, it is included at the end of the head tag.
|
||||
If `partials/paige-body-last.html` exists in the site, it is included at the end of the body tag.
|
||||
|
||||
Most code is in partial templates that are included by the default layouts.
|
||||
Elements can easily be added or changed by overriding the corresponding layout or partial template.
|
||||
|
||||
For example, the default layouts `home.html`, `list.html`, `single.html`, `taxonomy.html`, and `term.html` include `paige-main.html`, which includes `paige-title.html`, `paige-description.html`, `paige-date.html`, and `paige-content.html`. To change the page title for all those layouts, change `paige-title.html`. To change the page title for `single.html`, replace the use of `paige-main.html` in `single.html` with the use of `paige-title.html`, `paige-description.html`, `paige-date.html`, and `paige-content.html`, then replace that use of `paige-title.html` with your own design.
|
||||
|
||||
## Design
|
||||
|
||||
The HTML author is the site author.
|
||||
@@ -66,69 +316,35 @@ The HTML description is the page description.
|
||||
|
||||
The HTML keywords is a union of the page keywords, tags, and categories.
|
||||
|
||||
The HTML title is the page title, followed by a middle dot, followed by
|
||||
the site title. If one is missing, the other is used without the middle
|
||||
dot. If both are the same for the home page, the title is the page
|
||||
title.
|
||||
The HTML title is the page title, followed by a middle dot, followed by the site title.
|
||||
If one is missing, the other is used without the middle dot.
|
||||
For the home page, the title is the page title, if any, or the site title otherwise.
|
||||
|
||||
The HTML body can have a header, a body, and a footer. The header has
|
||||
the menu, if any; the page title, if any; the page description, if any;
|
||||
and the page date, if any. The body has the page content, if any. The
|
||||
footer has the copyright notice, if any, and the theme link, if any.
|
||||
The HTML body can have a header, a body, and a footer.
|
||||
The header has the menu, if any; the page title, if any; the page description, if any; and the page date, if any.
|
||||
The body has the page content, if any.
|
||||
The footer has the copyright notice, if any, and the theme link, if any.
|
||||
|
||||
A menu item is highlighted if its path is a prefix of the path of the
|
||||
current page. For example, the menu item path `/foo/` matches the pages
|
||||
`content/foo/_index.md`, `content/foo/bar.md`, and
|
||||
`content/foo/bar/_index.md`. The menu item path `/` only matches the
|
||||
page `content/_index.md`.
|
||||
The page date is the publish date, if any; otherwise, it's the creation date.
|
||||
|
||||
The menu is configured with `menu.main` in `config.yaml`.
|
||||
|
||||
To show full pages instead of just the page title and description in a
|
||||
list page, set the list page parameter `paigeshowfullpages` to true.
|
||||
|
||||
The page date is the publish date, if any; otherwise, it's the creation
|
||||
date. To change the date format displayed, set the site parameter
|
||||
`paigedateformat` to a Hugo date format.
|
||||
|
||||
The home page body has the `stretch`, `center`, `greeting`, and `blurb`
|
||||
parameters from `content/_index.md`, if any; the page content, if any;
|
||||
and linked icons for the social sites configured in `config.yaml`, if
|
||||
any. `stretch` is an image that is stretched fully horizontally with
|
||||
`background-position: center` and `background-size: cover`. `center` is
|
||||
an image that is centered.
|
||||
|
||||
Single pages use the `link` page parameter, if any, as the reference for
|
||||
an anchor around the page title, if any. If the page or site parameter
|
||||
`math` is set to true, math typesetting is enabled with KaTeX.
|
||||
|
||||
The `paige-search` layout provides full site search. It requires setting
|
||||
`outputs.home` to `["html", "json", "rss"]` in `config.yaml`.
|
||||
|
||||
Set page parameter `excluderss` to true to exclude it from RSS. Doing so
|
||||
for a list page excludes the entire directory.
|
||||
|
||||
Set page parameter `excludesearch` to true to exclude it from search.
|
||||
|
||||
If `partials/paige-head-last.html` exists in the site, it is included at
|
||||
the end of the head tag. If `partials/paige-body-last.html` exists in
|
||||
the site, it is included at the end of the body tag.
|
||||
|
||||
To hide the theme link, set the site parameter `paigehidethemelink` to
|
||||
true. To hide the theme comment, set the site parameter
|
||||
`paigehidethemecomment` to true. If you hide either of these, please
|
||||
credit this project in a post so others may find it.
|
||||
|
||||
Bootstrap 5.2.2 CSS and JavaScript and Bootstrap Icons 1.10.2 are loaded
|
||||
from the Bootstrap CDN for every page. To load local assets instead, set
|
||||
the site parameters `paigebootstrapcss`, `paigebootstrapicons`, and
|
||||
`paigebootstrapjs` to the asset paths.
|
||||
|
||||
## Configuration
|
||||
|
||||
See the example site directory for an example configuration.
|
||||
Bootstrap 5.2.2 CSS and JavaScript and Bootstrap Icons 1.10.2 are loaded from the Bootstrap CDN for every page unless local Bootstrap assets are used instead.
|
||||
|
||||
## Credits
|
||||
|
||||
- Center photo by [Yuvraj Singh](https://unsplash.com/photos/ljziSm0DXg8)
|
||||
- Stretch photo by [Sergey Pesterev](https://unsplash.com/photos/JV78PVf3gGI)
|
||||
|
||||
## Community
|
||||
|
||||
Get started by [starring](https://github.com/willfaught/paige/stargazers)
|
||||
and [following](https://github.com/willfaught/paige/watchers) the project.
|
||||
|
||||
If you find an issue, please [report it](https://github.com/willfaught/paige/issues/new).
|
||||
If you have fixes or improvements, please [create a pull request](https://github.com/willfaught/paige/compare).
|
||||
Feedback is encouraged and appreciated.
|
||||
|
||||
## Project
|
||||
|
||||
Created by [Will Faught](https://github.com/willfaught).
|
||||
Released under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
|
||||
Hosted at https://github.com/willfaught/paige.
|
||||
|
Reference in New Issue
Block a user