|
1 |
| -# Docsy Example |
| 1 | +# Website |
2 | 2 |
|
3 |
| -[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy |
4 |
| -site navigation, structure, and more. This **Docsy Example Project** uses the Docsy |
5 |
| -theme component as a hugo module and provides a skeleton documentation structure for you to use. |
6 |
| -You can clone/copy this project and edit it with your own content, or use it as an example. |
| 3 | +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. |
7 | 4 |
|
8 |
| -In this project, the Docsy theme component is pulled in as a Hugo module, together with other module dependencies: |
| 5 | +### Installation |
9 | 6 |
|
10 |
| -```bash |
11 |
| -$ hugo mod graph |
12 |
| -hugo: collected modules in 566 ms |
13 |
| -hugo: collected modules in 578 ms |
14 |
| -github.com/google/docsy-example github.com/google/ [email protected] |
15 |
| -github.com/google/docsy-example github.com/google/docsy/ [email protected] |
16 |
| -github.com/google/docsy/ [email protected] github.com/twbs/ [email protected]+incompatible |
17 |
| -github.com/google/docsy/ [email protected] github.com/FortAwesome/ [email protected] |
18 | 7 | ```
|
19 |
| - |
20 |
| -You can find detailed theme instructions in the [Docsy user guide][]. |
21 |
| - |
22 |
| -This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][]. |
23 |
| -You can view deploy logs from the [deploy section of the project's Netlify |
24 |
| -dashboard][deploys], or this [alternate dashboard][]. |
25 |
| - |
26 |
| -This is not an officially supported Google product. This project is currently maintained. |
27 |
| - |
28 |
| -## Using the Docsy Example Project as a template |
29 |
| - |
30 |
| -A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this: |
31 |
| - |
32 |
| -1. Click **Use this template**. |
33 |
| - |
34 |
| -2. Select a name for your new project and click **Create repository from template**. |
35 |
| - |
36 |
| -3. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL: |
37 |
| - |
38 |
| -```bash |
39 |
| -git clone --depth 1 https://github.com/me/example.git |
| 8 | +$ yarn |
40 | 9 | ```
|
41 | 10 |
|
42 |
| -You can now edit your own versions of the site’s source files. |
43 |
| - |
44 |
| -If you want to do SCSS edits and want to publish these, you need to install `PostCSS` |
| 11 | +### Local Development |
45 | 12 |
|
46 |
| -```bash |
47 |
| -npm install |
| 13 | +``` |
| 14 | +$ yarn start |
48 | 15 | ```
|
49 | 16 |
|
50 |
| -## Running the website locally |
51 |
| - |
52 |
| -Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io). |
53 |
| -You can find out more about how to install Hugo for your environment in our |
54 |
| -[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide. |
| 17 | +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. |
55 | 18 |
|
56 |
| -Once you've made your working copy of the site repo, from the repo root folder, run: |
| 19 | +### Build |
57 | 20 |
|
58 | 21 | ```
|
59 |
| -hugo server |
| 22 | +$ yarn build |
60 | 23 | ```
|
61 | 24 |
|
62 |
| -## Running a container locally |
63 |
| - |
64 |
| -You can run docsy-example inside a [Docker](https://docs.docker.com/) |
65 |
| -container, the container runs with a volume bound to the `docsy-example` |
66 |
| -folder. This approach doesn't require you to install any dependencies other |
67 |
| -than [Docker Desktop](https://www.docker.com/products/docker-desktop) on |
68 |
| -Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/) |
69 |
| -on Linux. |
70 |
| - |
71 |
| -1. Build the docker image |
72 |
| - |
73 |
| - ```bash |
74 |
| - docker-compose build |
75 |
| - ``` |
| 25 | +This command generates static content into the `build` directory and can be served using any static contents hosting service. |
76 | 26 |
|
77 |
| -1. Run the built image |
| 27 | +### Deployment |
78 | 28 |
|
79 |
| - ```bash |
80 |
| - docker-compose up |
81 |
| - ``` |
| 29 | +Using SSH: |
82 | 30 |
|
83 |
| - > NOTE: You can run both commands at once with `docker-compose up --build`. |
84 |
| -
|
85 |
| -1. Verify that the service is working. |
86 |
| - |
87 |
| - Open your web browser and type `http://localhost:1313` in your navigation bar, |
88 |
| - This opens a local instance of the docsy-example homepage. You can now make |
89 |
| - changes to the docsy example and those changes will immediately show up in your |
90 |
| - browser after you save. |
91 |
| - |
92 |
| -### Cleanup |
93 |
| - |
94 |
| -To stop Docker Compose, on your terminal window, press **Ctrl + C**. |
95 |
| - |
96 |
| -To remove the produced images run: |
97 |
| - |
98 |
| -```console |
99 |
| -docker-compose rm |
100 | 31 | ```
|
101 |
| -For more information see the [Docker Compose |
102 |
| -documentation](https://docs.docker.com/compose/gettingstarted/). |
103 |
| - |
104 |
| -## Troubleshooting |
105 |
| - |
106 |
| -As you run the website locally, you may run into the following error: |
107 |
| - |
108 |
| -``` |
109 |
| -➜ hugo server |
110 |
| -
|
111 |
| -INFO 2021/01/21 21:07:55 Using config file: |
112 |
| -Building sites … INFO 2021/01/21 21:07:55 syncing static files to / |
113 |
| -Built in 288 ms |
114 |
| -Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache |
| 32 | +$ USE_SSH=true yarn deploy |
115 | 33 | ```
|
116 | 34 |
|
117 |
| -This error occurs if you have not installed the extended version of Hugo. |
118 |
| -See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo. |
119 |
| - |
120 |
| -Or you may encounter the following error: |
| 35 | +Not using SSH: |
121 | 36 |
|
122 | 37 | ```
|
123 |
| -➜ hugo server |
124 |
| -
|
125 |
| -Error: failed to download modules: binary with name "go" not found |
| 38 | +$ GIT_USER=<Your GitHub username> yarn deploy |
126 | 39 | ```
|
127 | 40 |
|
128 |
| -This error occurs if you have not installed the `go` programming language on your system. |
129 |
| -See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`. |
130 |
| - |
131 |
| - |
132 |
| -[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys |
133 |
| -[deploys]: https://app.netlify.com/sites/docsy-example/deploys |
134 |
| -[Docsy user guide]: https://docsy.dev/docs |
135 |
| -[Docsy]: https://github.com/google/docsy |
136 |
| -[example.docsy.dev]: https://example.docsy.dev |
137 |
| -[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme |
138 |
| -[Netlify]: https://netlify.com |
| 41 | +If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. |
0 commit comments