diff options
Diffstat (limited to 'themes/docsy/README.md')
| -rw-r--r-- | themes/docsy/README.md | 52 |
1 files changed, 34 insertions, 18 deletions
diff --git a/themes/docsy/README.md b/themes/docsy/README.md index f61eff67c..89dde4e5c 100644 --- a/themes/docsy/README.md +++ b/themes/docsy/README.md @@ -1,34 +1,50 @@ # Docsy -Docsy is a Hugo theme for technical documentation sets, providing simple navigation, site structure, and more. +Docsy is a [Hugo](https://gohugo.io/) theme for technical documentation sets, providing simple navigation, site structure, and more. -You can find an example project that uses Docsy in the [Docsy Example Project repo](https://github.com/google/docsy-example). The Docsy Example Project is hosted at [https://testydocsy.netlify.com/](https://testydocsy.netlify.com/), where you can find detailed theme instructions under **Documentation -> Getting Started**. +This is not an officially supported Google product. This project is actively being maintained. -To use the Docsy theme, you can either: +## Prerequisites -* Copy and edit the example site’s repo, which will also give you a skeleton structure for your top-level and documentation sections, or -* Specify the Docsy theme like any other [Hugo theme](https://gohugo.io/themes/installing-and-using-themes/) - when creating or updating your site. This gives you all the theme-y goodness but you’ll need to specify your own site structure. +The following are basic prerequisites for using Docsy in your site: -This is not an officially supported Google product. This project is currently maintained. +- Install a recent release of the Hugo "extended" version (we recommend version 0.53 or later). If you install from the + [release page](https://github.com/gohugoio/hugo/releases), make sure you download the `_extended` version + which supports SCSS. -## Installation and prerequisites +- Install `PostCSS` so that the site build can create the final CSS assets. You can install it locally by running + the following commands from the root directory of your project: -You need a recent version of Hugo to build sites using this theme (preferably 0.45+). If you install from the [release page](https://github.com/gohugoio/hugo/releases), make sure to get the `extended` Hugo version which supports SCSS. Alternatively, on macOS you can install Hugo via Brew. + ``` + sudo npm install -D --save autoprefixer + sudo npm install -D --save postcss-cli + ``` -If you want to do stylesheet changes, you will also need `PostCSS` to create the final assets. You can also install it locally with: +## Example and usage -``` -npm install -```` +You can find an example project that uses Docsy in the [Docsy Example Project repo](https://github.com/google/docsy-example). The Docsy Example Project is hosted at [https://example.docsy.dev/](https://example.docsy.dev/). + +To use the Docsy theme for your own site: + + - (Recommended) Copy the [example project](https://github.com/google/docsy-example), + which includes the Docsy theme as a submodule. + You can customize this pre-configured basic site into your own Docsy themed site. + [Learn more...](https://github.com/google/docsy-example) + + - Add Docsy to your existing Hugo site repo's `themes` directory. You can either add Docsy as a Git submodule, or + clone the Docsy theme into your project. -To use a local version of the theme files, clone the repo using: +See the [Docsy Getting Started Guide](https://docsy.dev/docs/getting-started/) for +details about the various usage options. + +## Documentation + +Docsy has its own user guide (using Docsy, of course!) with lots more information about using the theme, which you can find at [https://docsy.dev/](https://docsy.dev/). Alternatively you can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above: ``` git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git +cd docsy/userguide/ +hugo server --themesDir ../.. ``` -## Theme documentation - -Detailed documentation for this theme is in the Docsy Example Project under **Documentation -> Getting Started**. -The Docsy Example Project is on [GitHub](https://github.com/google/docsy-example) and is hosted at [https://testydocsy.netlify.com/](https://testydocsy.netlify.com/). +Note that you need the `themesDir` flag when running Hugo because the site files are inside the theme repo. |