You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines "as is" or adapt them with your own instructions: for example, other deployment options, information about your doc project's file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. [Kubeflow](https://github.com/kubeflow/website/blob/master/README.md) has a great example.
8
+
Welcome to the GitHub repository for Layer5's documentation website!
9
9
10
-
Don't forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.
11
-
{{% /pageinfo %}}
10
+
The docs website is hosted at https://docs.layer5.io.
12
11
13
-
We use [Hugo](https://gohugo.io/) to format and generate our website, the
14
-
[Docsy](https://github.com/google/docsy) theme for styling and site structure,
15
-
and [Netlify](https://www.netlify.com/) to manage the deployment of the site.
16
-
Hugo is an open-source static site generator that provides us with templates,
17
-
content organisation in a standard directory structure, and a website generation
18
-
engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.
12
+
We use [Hugo](https://gohugo.io/) with the [google/docsy](https://github.com/google/docsy) theme for styling and site structure, and [Netlify](https://www.netlify.com/) to manage the deployment of the site.
19
13
20
-
All submissions, including submissions by project members, require review. We
21
-
use GitHub pull requests for this purpose. Consult
22
-
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
23
-
information on using pull requests.
14
+
## Quickstart
24
15
25
-
## Quick start with Netlify
16
+
Here's a quick guide to updating the docs:
26
17
27
-
Here's a quick guide to updating the docs. It assumes you're familiar with the
28
-
GitHub workflow and you're happy to use the automated preview of your doc
29
-
updates:
18
+
1. Fork the [layer5io/docs repository](https://github.com/layer5io/docs) on GitHub.
30
19
31
-
1. Fork the [Goldydocs repo](https://github.com/google/docsy-example) on GitHub.
32
-
1. Make your changes and send a pull request (PR).
33
-
1. If you're not yet ready for a review, add "WIP" to the PR name to indicate
34
-
it's a work in progress. (**Don't** add the Hugo property
35
-
"draft = true" to the page front matter, because that prevents the
36
-
auto-deployment of the content preview described in the next point.)
37
-
1. Wait for the automated PR workflow to do some checks. When it's ready,
38
-
you should see a comment like this: **deploy/netlify — Deploy preview ready!**
39
-
1. Click **Details** to the right of "Deploy preview ready" to see a preview
40
-
of your updates.
41
-
1. Continue updating your doc and pushing your changes until you're happy with
42
-
the content.
43
-
1. When you're ready for a review, add a comment to the PR, and remove any
44
-
"WIP" markers.
20
+
2. Make your changes and send a pull request (PR).
45
21
46
-
## Updating a single page
22
+
3. If you're not yet ready for a review, add "WIP" to the PR name to indicate it's a work in progress.
23
+
Alternatively, you use the `/hold`[prow command](https://prow.k8s.io/command-help) in a comment to mark the PR as not ready for merge.
47
24
48
-
If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
25
+
4. Wait for the automated PR workflow to do some checks.
26
+
When it's ready, you should see a comment like this: `deploy/netlify — Deploy preview ready!`
49
27
50
-
1. Click **Edit this page** in the top right hand corner of the page.
51
-
1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
52
-
1. Follow the rest of the [Quick start with Netlify](#quick-start-with-netlify) process above to make, preview, and propose your changes.
28
+
5. Click **Details** to the right of "Deploy preview ready" to see a preview of your updates.
53
29
54
-
## Previewing your changes locally
30
+
6. Continue updating your doc and pushing your changes until you're happy with the content.
55
31
56
-
If you want to run your own local Hugo server to preview your changes as you work:
32
+
7. When you're ready for a review, add a comment to the PR, remove any holds or "WIP" markers, and assign a reviewer/approver.
33
+
See the [Layer5 contributor guide](https://docs.layer5.io/docs/about/contributing/).
57
34
58
-
1. Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need. You'll need at least **Hugo version 0.45** (we recommend using the most recent available version), and it must be the **extended** version, which supports SCSS.
59
-
1. Fork the [Goldydocs repo](https://github.com/google/docsy-example) repo into your own project, then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site.
35
+
If you need more help with the GitHub workflow, follow
36
+
this [guide to a standard GitHub workflow](https://github.com/layer5io/docs/blob/master/quick-github-guide.md).
60
37
38
+
## Local development
39
+
40
+
This section will show you how to develop the website locally, by running a local Hugo server.
41
+
42
+
### Install Hugo
43
+
44
+
To install Hugo, follow the [instructions for your system type](https://gohugo.io/getting-started/installing/).
45
+
46
+
**NOTE:** we recommend that you use Hugo version `0.119.0`, as this is currently the version we deploy to Netlify.
47
+
48
+
For example, using homebrew to install hugo on macOS or linux:
49
+
50
+
```bash
51
+
# WARNING: this may install a newer version than `0.119.0`
52
+
brew install hugo
53
+
```
54
+
55
+
### Install Node Packages
56
+
57
+
If you plan to make changes to the site styling, you need to install some **node libraries** as well.
58
+
(See the [Docsy setup guide](https://www.docsy.dev/docs/getting-started/#install-postcss) for more information)
59
+
60
+
You can install the same versions we use in Netlify (defined in `package.json`) with the following command:
61
+
62
+
```bash
63
+
npm install -D
64
+
```
65
+
66
+
### Run local hugo server
67
+
68
+
Follow the usual GitHub workflow of forking the repository on GitHub and then cloning your fork to your local machine.
69
+
70
+
1.**Fork** the [layer5io/docs repository](https://github.com/layer5io/docs) in the GitHub UI.
1. Run `hugo server` in the site root directory. By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
66
-
1. Continue with the usual GitHub workflow to edit files, commit them, push the
67
-
changes up to your fork, and create a pull request.
85
+
4. Install Docsy dependencies:
86
+
87
+
```bash
88
+
# NOTE: ensure you have node 18 installed
89
+
(cd themes/docsy/ && npm install)
90
+
```
91
+
92
+
5. Start your local Hugo server:
93
+
94
+
```bash
95
+
hugo server -D
96
+
```
97
+
98
+
6. You can access your website at [http://localhost:1313/](http://localhost:1313/)
99
+
100
+
### Useful docs
101
+
102
+
* [User guide for the Docsy theme](https://www.docsy.dev/docs/getting-started/)
* [Hugo site directory structure](https://gohugo.io/getting-started/directory-structure/)
106
+
* [hugo server reference](https://gohugo.io/commands/hugo_server/)
107
+
108
+
## Menu structure
109
+
110
+
The site theme has one Hugo menu (`main`), which defines the top navigation bar. You can find and adjust the definition
111
+
of the menu in the [site configuration file](https://github.com/layer5io/docs/blob/master/config.toml).
112
+
113
+
The left-hand navigation panel is defined by the directory structure under the [`docs` directory](https://github.com/layer5io/docs/tree/master/content/en/docs).
114
+
115
+
A `weight` property in the _front matter_ of each page determines the position of the page relative to the others in the same directory.
116
+
The lower the weight, the earlier the page appears in the section.
117
+
118
+
Here is an example `_index.md` file:
119
+
120
+
```md
121
+
+++
122
+
title = "Getting Started with Layer5"
123
+
description = "Overview"
124
+
weight = 1
125
+
+++
126
+
```
127
+
128
+
## Docsy Theme
129
+
130
+
We use the [Docsy](https://www.docsy.dev/) theme for the website.
131
+
The theme files are managed with a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) in the `themes/docsy` directory.
132
+
133
+
**Do not change these files**, they are not actually inside this repo, but are part of the [google/docsy](https://github.com/google/docsy) repo.
134
+
135
+
To update referenced docsy commit, run the following command at the root of the repo:
136
+
137
+
```bash
138
+
# for example, to update docsy to v0.6.0
139
+
# WARNING: updating the docsy version will require you to update our overrides
140
+
# check under: `layouts/partials` and `assets/scss`
141
+
git -C themes/docsy fetch --tags
142
+
git -C themes/docsy checkout tags/v0.6.0
143
+
```
144
+
145
+
## Documentation style guide
146
+
147
+
For guidance on writing effective documentation, see
148
+
the [style guide for the Layer5 docs](https://docs.layer5.io/docs/about/style-guide/).
149
+
150
+
## Styling your content
151
+
152
+
The theme holds its styles in the [`assets/scss` directory](https://github.com/layer5io/docs/tree/master/themes/docsy/assets/scss).
153
+
154
+
**Do not change these files**, they are not actually inside this repo, but are part of the [google/docsy](https://github.com/google/docsy) repo.
155
+
156
+
You can override the default styles and add new ones:
157
+
158
+
* In general, put your files in the project directory structure under `website` rather than in the theme directory.
159
+
Use the same file name as the theme does, and put the file in the same relative position.
160
+
Hugo looks first at the file in the main project directories, if present, then at the files under the theme directory.
161
+
For example, the Layer5 website's [`layouts/partials/navbar.html`](https://github.com/layer5io/docs/blob/master/layouts/partials/navbar.html)
162
+
overrides the theme's [`layouts/partials/navbar.html`](https://github.com/layer5io/docs/blob/master/themes/docsy/layouts/partials/navbar.html)
163
+
164
+
* You can update the Layer5 website's project variables in the [`_variables_project.scss` file](https://github.com/layer5io/docs/blob/master/assets/scss/_variables_project.scss).
165
+
Values in that file override the [Docsy variables](https://github.com/layer5io/docs/blob/master/themes/docsy/assets/scss/_variables.scss).
166
+
You can also use `_variables_project.scss` to specify your own values for any of the default [Bootstrap 4 variables](https://getbootstrap.com/docs/4.0/getting-started/theming/).
* To see some examples of styled images, take a look at the [OAuth setup page](https://docs.layer5.io/docs/gke/deploy/oauth-setup/) in the Layer5 docs.
173
+
Search for `.png` in the [page source](https://raw.githubusercontent.com/layer5io/docs/master/content/en/docs/gke/deploy/oauth-setup.md).
For each stable release, we create a new branch for the relevant documentation.
244
+
For example, the documentation forthe v0.2 stable release is maintainedin the [v0.2-branch](https://github.com/layer5io/docs/tree/v0.2-branch).
245
+
Each branch has a corresponding Netlify website that automatically syncs each merged PR.
68
246
69
-
## Creating an issue
247
+
The versioned sites follow this convention:
70
248
71
-
If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [Goldydocs repo](https://github.com/google/docsy-example/issues). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page.
249
+
*`docs.layer5.io` always points to the current *master branch*
250
+
*`master.docs.layer5.io` always points to GitHub head
251
+
*`vXXX-YYY.docs.layer5.io` points to the release at vXXX.YYY-branch
72
252
73
-
## Useful resources
253
+
We also hook up each version to the dropdown on the website menu bar.
254
+
For information on how to update the website to a new version, see the [Layer5 release guide](https://github.com/layer5io/docs/blob/master/docs_dev/releasing.md#releasing-a-new-version-of-the-website).
74
255
75
-
* [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including how it manages navigation, look and feel, and multi-language support.
76
-
* [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo.
77
-
* [Github Hello World!](https://guides.github.com/activities/hello-world/): A basic introduction to GitHub concepts and workflow.
256
+
Whenever any documents reference any source code, you should use the version shortcode in the links, like so:
0 commit comments