-
Notifications
You must be signed in to change notification settings - Fork 888
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README: markdown cleanup, line-wrapping, etc (#892)
- Loading branch information
Showing
1 changed file
with
53 additions
and
31 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,59 +1,81 @@ | ||
| # Docsy | ||
| # Docsy | ||
|
|
||
| Docsy is a [Hugo](https://gohugo.io/) 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. | ||
|
|
||
| This is not an officially supported Google product. This project is actively being maintained. | ||
| This is not an officially supported Google product. This project is actively | ||
| being maintained. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| The following are basic prerequisites for using Docsy in your site: | ||
|
|
||
| - 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. | ||
| - 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. | ||
|
|
||
| - 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: | ||
| - 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: | ||
|
|
||
| ``` | ||
| sudo npm install -D --save autoprefixer | ||
| sudo npm install -D --save postcss-cli | ||
| ```console | ||
| $ sudo npm install -D --save autoprefixer | ||
| $ sudo npm install -D --save postcss-cli | ||
| ``` | ||
|
|
||
| ## Example and usage | ||
|
|
||
| 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/). For real-life examples of sites that use Docsy (and their source repos), see our [Examples](https://www.docsy.dev/docs/examples/) page. | ||
| 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). For | ||
| real-life examples of sites that use Docsy (and their source repos), see our | ||
| [Examples](https://www.docsy.dev/docs/examples/) page. | ||
|
|
||
| To use the Docsy theme for your own site: | ||
|
|
||
| - (Recommended) Use the [example project](https://github.com/google/docsy-example), | ||
| which includes the Docsy theme as a submodule, as a template to create your project. | ||
| 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. | ||
| - (Recommended) Use the [example | ||
| project](https://github.com/google/docsy-example), which includes the Docsy | ||
| theme as a submodule, as a template to create your project. You can customize | ||
| this pre-configured basic site into your own Docsy themed site. [Learn | ||
| more...](https://github.com/google/docsy-example) | ||
|
|
||
| See the [Docsy Getting Started Guide](https://docsy.dev/docs/getting-started/) for | ||
| details about the various usage options. | ||
| - 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. | ||
|
|
||
| ## Documentation | ||
| See the [Docsy Getting Started Guide](https://docsy.dev/docs/getting-started/) | ||
| for details about the various usage options. | ||
|
|
||
| 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: | ||
| ## Documentation | ||
|
|
||
| ``` | ||
| git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git | ||
| cd docsy/userguide/ | ||
| hugo server --themesDir ../.. | ||
| 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: | ||
|
|
||
| ```console | ||
| $ git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git | ||
| $ cd docsy/userguide/ | ||
| $ hugo server --themesDir ../.. | ||
| ``` | ||
|
|
||
| Note: you need the `themesDir` flag when running Hugo because the site files are inside the theme repo. | ||
| Note: you need the `themesDir` flag when running Hugo because the site files are | ||
| inside the theme repo. | ||
|
|
||
| ## Contributing  | ||
|
|
||
| Please read [CONTRIBUTING.md](https://github.com/google/docsy/blob/master/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. | ||
| See also the list of [contributors](https://github.com/google/docsy/graphs/contributors) who participated in this project. | ||
| Please read | ||
| [CONTRIBUTING.md](https://github.com/google/docsy/blob/master/CONTRIBUTING.md) | ||
| for details on our code of conduct, and the process for submitting pull requests | ||
| to us. See also the list of | ||
| [contributors](https://github.com/google/docsy/graphs/contributors) who | ||
| participated in this project. | ||
|
|
||
| ## License  | ||
|
|
||
| This project is licensed under the Apache License 2.0 - see the [LICENSE.md](https://github.com/google/docsy/blob/master/LICENSE) file for details | ||
| This project is licensed under the Apache License 2.0 - see the | ||
| [LICENSE.md](https://github.com/google/docsy/blob/master/LICENSE) file for | ||
| details |