|
1 | | -# Docsy Example |
| 1 | +# Ottercast Website |
2 | 2 |
|
3 | | -[Docsy](https://github.com/google/docsy) is a Hugo theme for technical documentation sites, providing easy site navigation, structure, and more. This **Docsy Example Project** uses the Docsy theme, as well as providing a skeleton documentation structure for you to use. You can either copy this project and edit it with your own content, or use the theme in your projects like any other [Hugo theme](https://gohugo.io/themes/installing-and-using-themes/). |
| 3 | +These are the source files for the [ottercast](https://cast.otter.jetzt/) website. |
| 4 | +Feel free to send a pull request or open a issue (for documentation errors, missing info, etc.). |
4 | 5 |
|
5 | | -The theme is included in this project as a Git submodule: |
6 | | - |
7 | | -```bash |
8 | | -▶ git submodule |
9 | | - a053131a4ebf6a59e4e8834a42368e248d98c01d themes/docsy (heads/master) |
10 | | -``` |
11 | | - |
12 | | -This Docsy Example Project is hosted at [https://example.docsy.dev/](https://example.docsy.dev/). |
13 | | - |
14 | | -You can find detailed theme instructions in the Docsy user guide: https://docsy.dev/docs/ |
15 | | - |
16 | | -This is not an officially supported Google product. This project is currently maintained. |
17 | | - |
18 | | -## Using the Docsy Example Project as a template |
19 | | - |
20 | | -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: |
21 | | - |
22 | | -1. Click **Use this template**. |
23 | | - |
24 | | -2. Select a name for your new project and click **Create repository from template**. |
25 | | - |
26 | | -3. Make your own local working copy of your new repo using git clone, replacing https://github.com/my/example.git with your repo’s web URL: |
27 | | - |
28 | | -```bash |
29 | | -git clone --recurse-submodules --depth 1 https://github.com/my/example.git |
30 | | -``` |
31 | | - |
32 | | -You can now edit your own versions of the site’s source files. |
33 | | - |
34 | | -If you want to do SCSS edits and want to publish these, you need to install `PostCSS` |
35 | | - |
36 | | -```bash |
37 | | -npm install |
38 | | -``` |
39 | | - |
40 | | -## Running the website locally |
41 | | - |
42 | | -Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io). |
43 | | -You can find out more about how to install Hugo for your environment in our |
44 | | -[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide. |
45 | | - |
46 | | -Once you've made your working copy of the site repo, from the repo root folder, run: |
47 | | - |
48 | | -``` |
49 | | -hugo server |
50 | | -``` |
51 | | - |
52 | | -## Running a container locally |
53 | | - |
54 | | -You can run docsy-example inside a [Docker](https://docs.docker.com/) |
55 | | -container, the container runs with a volume bound to the `docsy-example` |
56 | | -folder. This approach doesn't require you to install any dependencies other |
57 | | -than [Docker Desktop](https://www.docker.com/products/docker-desktop) on |
58 | | -Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/) |
59 | | -on Linux. |
60 | | - |
61 | | -1. Build the docker image |
62 | | - |
63 | | - ```bash |
64 | | - docker-compose build |
65 | | - ``` |
66 | | - |
67 | | -1. Run the built image |
68 | | - |
69 | | - ```bash |
70 | | - docker-compose up |
71 | | - ``` |
72 | | - |
73 | | - > NOTE: You can run both commands at once with `docker-compose up --build`. |
74 | | -
|
75 | | -1. Verify that the service is working. |
76 | | - |
77 | | - Open your web browser and type `http://localhost:1313` in your navigation bar, |
78 | | - This opens a local instance of the docsy-example homepage. You can now make |
79 | | - changes to the docsy example and those changes will immediately show up in your |
80 | | - browser after you save. |
81 | | - |
82 | | -### Cleanup |
83 | | - |
84 | | -To stop Docker Compose, on your terminal window, press **Ctrl + C**. |
85 | | - |
86 | | -To remove the produced images run: |
87 | | - |
88 | | -```console |
89 | | -docker-compose rm |
90 | | -``` |
91 | | -For more information see the [Docker Compose |
92 | | -documentation](https://docs.docker.com/compose/gettingstarted/). |
93 | | - |
94 | | -## Troubleshooting |
95 | | - |
96 | | -As you run the website locally, you may run into the following error: |
97 | | - |
98 | | -``` |
99 | | -➜ hugo server |
100 | | -
|
101 | | -INFO 2021/01/21 21:07:55 Using config file: |
102 | | -Building sites … INFO 2021/01/21 21:07:55 syncing static files to / |
103 | | -Built in 288 ms |
104 | | -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 |
105 | | -``` |
106 | | - |
107 | | -This error occurs if you have not installed the extended version of Hugo. |
108 | | -See our [user guide](https://www.docsy.dev/docs/getting-started/) for instructions on how to install Hugo. |
| 6 | +This website is built using Hugo and the Docsy template: |
| 7 | +https://github.com/google/docsy |
109 | 8 |
|
| 9 | +For development, clone this repo, get the extended (!) version of Hugo and run: |
| 10 | +`hugo server` |
| 11 | +You can then access the site at http://localhost:1313/ |
0 commit comments