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
Copy file name to clipboardExpand all lines: CONTRIBUTING/README.md
+35-73
Original file line number
Diff line number
Diff line change
@@ -7,127 +7,89 @@ When you contribute to the docs, it helps to know how things work.
7
7
8
8
-[Important directories](#important-directories)
9
9
-[Build locally](#build-locally)
10
-
-[Necessary software](#necessary-software)
11
-
-[Build procedure](#build-procedure)
10
+
-[Before you begin](#before-you-begin)
11
+
-[Build and preview](#build-and-preview)
12
12
-[Write](#write)
13
13
-[Style Guides](#style-guides)
14
-
-[Gatsby components](#gatsby-components)
15
-
-[Troubleshooting](#troubleshooting)
14
+
-[Shortcodes](#shortcodes)
16
15
-[Deploy](#deploy)
17
16
-[Upgrade a main release](#upgrade-a-main-release)
18
17
19
18
<!-- markdown-toc end -->
20
19
21
-
22
20
## Important directories
23
21
24
22
For writers, these are the most important directories:
25
-
-[`src/data/markdown`](../src/data/markdown) is where the docs live
26
-
-`translated-guides` has the principle OSS docs
27
-
-[`gatsby-node.js`](../gatsby-node.js) is where URI redirects are programmed.
28
-
-[`src/templates/docs`](../src/templates/docs) has the "landing pages" for major docs sections: cloud, guides, examples, et cetera.
29
-
-[`src/components/shared`](../src/components/shared) has the reusable writing enhancements, like our stylish `<blockquote>`
23
+
24
+
-[`docs/sources`](../docs/sources) is where the docs live.
25
+
-`docs/sources/VERSION/shared` has Markdown files that can be reused across multiple pages by using the [`shared` shortcode](https://grafana.com/docs/writers-toolkit/write/shortcodes/#docsshared).
30
26
31
27
## Build locally
32
28
33
-
For any substantial changes, a local, live preview hugely improves writer comfort, which translates to better doc quality.
29
+
### Before you begin
34
30
35
-
### Necessary software
31
+
To build the k6 docs in your machine, you'll need:
36
32
37
-
If you don't want to build with Docker (refer to repo README), you'll need the following
38
-
-[NodeJS](https://nodejs.org/en/download/), version 16.0.0 or higher
39
-
- A node version manager like [`nvm`](https://github.com/nvm-sh/nvm#installing-and-updating) or `fnm`
40
-
-`npm` or `yarn`
33
+
-[Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation)
41
34
42
-
### Build procedure
35
+
If you're using Docker, make sure you have the Docker Desktop application running.
2. Use the version manager to install a version of node compatible with the version in `package.json`.
45
+
Navigate to the `docs` directory and run `make docs`:
54
46
55
-
```bash
56
-
nvm install 16.16
57
-
nvm use 16.16
58
-
```
47
+
```bash
48
+
cd docs && make docs
49
+
```
59
50
60
-
3. Install dependencies (only necessary the first time).
51
+
You should see an output similar to this when the site finishes building:
61
52
62
-
```bash
63
-
npm install # or yarn install
64
-
```
53
+
```bash
54
+
View documentation locally:
55
+
http://localhost:3002/docs/k6/
65
56
66
-
4. Run the docs locally.
57
+
Press Ctrl+C to stop the server
58
+
```
67
59
68
-
```bash
69
-
npm start # or yarn start
70
-
```
60
+
Go to http://localhost:3002/docs/k6/, and you should be able to see a preview of the docs.
71
61
72
-
If everything works, a live preview should be serving on http://localhost:8000.
73
-
Things don't always work, though. The [Troubleshooting](./troubleshooting) section covers some common breaks.
62
+
Refer to [Writers' Toolkit, Build and review documentation](https://grafana.com/docs/writers-toolkit/review/) for more details about how to build the docs, and tools you can use such as Vale.
74
63
75
64
## Write
76
65
77
-
Each Markdown page should start with the following frontmatter.
66
+
Each Markdown page should start with the following front matter.
78
67
79
68
```yaml
80
69
---
81
70
title: <page title>
82
-
excerpt: <summary text for social shares. Aim for 170 characters>.
71
+
description: <summary text for search engines and social shares. Aim for 170 characters>.
83
72
---
84
73
```
85
74
86
75
### Style guides
87
76
88
77
- k6 follows the style prescribed in the [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/), which itself inherits most of its rules from the [Google developer documentation style guide](https://developers.google.com/style).
89
78
79
+
### Shortcodes
90
80
91
-
### Gatsby components
92
-
93
-
- To organize your pages on the site, Gatsby has a specific way to make paths and organize topics.
94
-
We've also added a number of writing enhancements, like nested tables, tabbed code fences, and collapsible sections. For all syntax and components you can use, checkout the [Contributor's reference](./gatsby-reference.md).
81
+
- We've also added a number of writing enhancements, like admonitions, tabbed code fences, and collapsible sections. For all syntax and components you can use, checkout the [Writers' Toolkit, Shortcodes](https://grafana.com/docs/writers-toolkit/write/shortcodes/).
95
82
96
-
### Troubleshooting
97
-
98
-
-[Troubleshooting](troubleshooting.md) has fixes for common breaks.
83
+
Refer to [Writers' Toolkit, Write documentation](https://grafana.com/docs/writers-toolkit/write/) for more details about how to write new topics, how to use shortcodes, how to add images, and more.
99
84
100
85
## Deploy
101
86
102
-
GitHub actions build previews of the site in multiple stages:
103
-
104
-
1. Each PR to main gets a build preview at `https://mdr-ci.staging.k6.io/docs/refs/pull/<PR-NUMBER>/merge`. With every commit to the PR branch, the preview updates.
105
-
1. The main branch deploys to `staging.k6.io`
106
-
1.**After the repo release number is upgraded, the main branch deploys to `k6.io`**
Once a PR is merged to the main branch, if there are any changes made to the `docs/sources` folder, the GitHub Action [`publish-technical-documentation.yml`](https://github.com/grafana/k6-docs/blob/main/.github/workflows/publish-technical-documentation.yml) will sync the changes with the grafana/website repository, and the changes will be deployed to production soon after.
111
88
112
89
### Upgrade a main release
113
90
114
91
> #### ⚠️ Versions
115
92
>
116
-
> Versions follow the same major and minor numbers as github.com/grafana/k6. When cutting a new release of the docs between k6 releases, only increment the patch digits.
117
-
118
-
Before you upgrade versions, it's a good idea to give the updated docs a final look at `https://staging.k6.io`
119
-
**Especially check that redirects work and components render correctly!**
120
-
121
-
Unless k6 OSS has a version upgrade, increment the version by 0.0.1. For example, `0.43.1` → `0.43.2`
122
-
As the UI might change, refer to the GitHub [Managing releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) doc for the canonical instructions.
123
-
124
-
Each release has a tag, which you can create either through the Github CLI or from https://github.com/grafana/k6-docs/releases.
125
-
To upgrade through the UI:
126
-
127
-
1. From the releases page, select **Draft a new Release**.
> Versions follow the same major and minor numbers as github.com/grafana/k6.
132
94
133
-
1. For a small release (fixing a typo or broken link), you can manually add a short description. Otherwise, select **Generate release notes** to automatically include more information about what's changed, and then select **Publish release**.
95
+
TODO: Add step-by-step instructions for creating a new major version release.
2. Use the version manager to install a version of node compatible with the version in `package.json`.
54
+
55
+
```bash
56
+
nvm install 16.16
57
+
nvm use 16.16
58
+
```
59
+
60
+
3. Install dependencies (only necessary the first time).
61
+
62
+
```bash
63
+
npm install # or yarn install
64
+
```
65
+
66
+
4. Run the docs locally.
67
+
68
+
```bash
69
+
npm start # or yarn start
70
+
```
71
+
72
+
If everything works, a live preview should be serving on http://localhost:8000.
73
+
Things don't always work, though. The [Troubleshooting](./troubleshooting) section covers some common breaks.
74
+
75
+
## Write
76
+
77
+
Each Markdown page should start with the following front matter.
78
+
79
+
```yaml
80
+
---
81
+
title: <page title>
82
+
excerpt: <summary text for social shares. Aim for 170 characters>.
83
+
---
84
+
```
85
+
86
+
### Style guides
87
+
88
+
- k6 follows the style prescribed in the [Grafana Writers' Toolkit](https://grafana.com/docs/writers-toolkit/), which itself inherits most of its rules from the [Google developer documentation style guide](https://developers.google.com/style).
89
+
90
+
91
+
### Gatsby components
92
+
93
+
- To organize your pages on the site, Gatsby has a specific way to make paths and organize topics.
94
+
We've also added a number of writing enhancements, like nested tables, tabbed code fences, and collapsible sections. For all syntax and components you can use, checkout the [Contributor's reference](./gatsby-reference.md).
95
+
96
+
### Troubleshooting
97
+
98
+
-[Troubleshooting](troubleshooting.md) has fixes for common breaks.
99
+
100
+
## Deploy
101
+
102
+
GitHub actions build previews of the site in multiple stages:
103
+
104
+
1. Each PR to main gets a build preview at `https://mdr-ci.staging.k6.io/docs/refs/pull/<PR-NUMBER>/merge`. With every commit to the PR branch, the preview updates.
105
+
1. The main branch deploys to `staging.k6.io`
106
+
1.**After the repo release number is upgraded, the main branch deploys to `k6.io`**
> Versions follow the same major and minor numbers as github.com/grafana/k6. When cutting a new release of the docs between k6 releases, only increment the patch digits.
117
+
118
+
Before you upgrade versions, it's a good idea to give the updated docs a final look at `https://staging.k6.io`
119
+
**Especially check that redirects work and components render correctly!**
120
+
121
+
Unless k6 OSS has a version upgrade, increment the version by 0.0.1. For example, `0.43.1` → `0.43.2`
122
+
As the UI might change, refer to the GitHub [Managing releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) doc for the canonical instructions.
123
+
124
+
Each release has a tag, which you can create either through the Github CLI or from https://github.com/grafana/k6-docs/releases.
125
+
To upgrade through the UI:
126
+
127
+
1. From the releases page, select **Draft a new Release**.
1. For a small release (fixing a typo or broken link), you can manually add a short description. Otherwise, select **Generate release notes** to automatically include more information about what's changed, and then select **Publish release**.
0 commit comments