Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

README: markdown cleanup, line-wrapping, etc #892

Merged
merged 1 commit into from
Feb 14, 2022
Merged

README: markdown cleanup, line-wrapping, etc #892

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
84 changes: 53 additions & 31 deletions README.md
View file
Open in desktop
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 ![GitHub](https://img.shields.io/github/contributors/google/docsy)

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 ![GitHub](https://img.shields.io/github/license/google/docsy)

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