Add getting started help to readme

3 years ago · baef86c8ca
parent f3287bef77
commit baef86c8ca
1 changed files with 271 additions and 55 deletions
--- a/README.md
+++ b/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,77 +60,291 @@ Search page:
 - Social links
 - Twitter sharing

-## Design
+Soon: Dark color scheme and dynamic color schemes, when Bootstrap 5.3 releases.

-The HTML author is the site author.
+## Get started with Hugo

-The HTML description is the page description.
+1. [Install Hugo](https://gohugo.io/installation/).

-The HTML keywords is a union of the page keywords, tags, and categories.
+    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

-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.
+Example `config.yaml`:

-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.
+```yaml
+module:
+  imports:
+  - path: "github.com/willfaught/paige"
+```

-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`.
+Install:

-The menu is configured with `menu.main` in `config.yaml`.
+```sh
+$ hugo mod init github.com/youraccount/yourproject
+$ hugo mod get github.com/willfaught/paige
+```

-To show full pages instead of just the page title and description in a
-list page, set the list page parameter `paigeshowfullpages` to true.
+Update:

-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.
+```sh
+$ hugo mod get -u
+```

-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.
+### Option 2: Use a Git submodule

-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.
+Example `config.yaml`:

-The `paige-search` layout provides full site search. It requires setting
-`outputs.home` to `["html", "json", "rss"]` in `config.yaml`.
+```yaml
+theme: "paige"
+```

-Set page parameter `excluderss` to true to exclude it from RSS. Doing so
-for a list page excludes the entire directory.
+Install:

-Set page parameter `excludesearch` to true to exclude it from search.
+```sh
+$ cd yourproject
+$ git submodule add https://github.com/willfaught/paige themes/paige
+$ git submodule update --init --recursive --remote
+```

-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.
+Update:

-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.
+```sh
+$ cd yourproject
+$ git submodule update --recursive --remote
+```

-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.
+### Option 3: Use a copy

-## Configuration
+Example `config.yaml`:

-See the example site directory for an example configuration.
+```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.
+
+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.
+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 page date is the publish date, if any; otherwise, it's the creation date.
+
+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.