When you contribute to the docs, it helps to know how things work.
Table of Contents
For writers, these are the most important directories:
docs/sourcesis where the docs live.docs/sources/VERSION/sharedhas Markdown files that can be reused across multiple pages by using thesharedshortcode.src/data/markdowncontains the Markdown files for the legacy version of the docs, available at https://k6.io/docs. You do not need to update these files if you're making changes to the current or next version of the docs, available at https://grafana.com/docs/k6/latest/.
To build the k6 docs in your machine, you'll need:
If you're using Docker, make sure you have the Docker Desktop application running.
Clone the repository to your machine:
git clone https://github.com/grafana/k6-docs.gitRun npm start:
npm startYou should see an output similar to this when the site finishes building:
View documentation locally:
http://localhost:3002/docs/k6/
Press Ctrl+C to stop the serverGo to http://localhost:3002/docs/k6/, and you should be able to see a preview of the docs.
Refer to Writers' Toolkit, Build and review documentation for more details about how to build the docs, and tools you can use such as Vale.
You can find the Markdown file for the docs in the docs/sources folder. In that folder you'll find:
- A
nextfolder, which represents the docs for the next major release of k6. - Multiple version folders (for example, v0.47.x), which represents the docs for that specific version of k6.
Depending on the type of update you need to make, you'll want to make updates to different folders.
If you're making any updates or fixes that apply to the latest version of k6, you'll need to:
- Update the Markdown files in the
docs/sources/nextfolder. - Update the Markdown files in the
docs/sources/v{LATEST_VERSION}folder.- You can do this manually or by using the
apply-patchscript from thescriptsfolder. Refer to the Use theapply-patchscript section for more details.
- You can do this manually or by using the
This is to make sure that any changes you make are also brought over to the next major release version of k6.
If your update or fix also applies to previous versions of k6, use the
apply-patchscript to port your changes to the latest version, and two previous versions.
If you're making any updates or fixes that only apply to the next major release of k6, you'll need to:
- Update the Markdown files in the
docs/sources/nextfolder.
Once you make any changes and open a PR, and that PR is reviewed, you can merge it without having to worry about those changes showing up in the latest version of the docs. The latest version will always display the highest numbered version folder of the docs.
You can use the apply-patch script to port changes from one version folder to another. This is especially helpful if you're making updates or fixes to the latest version of k6, and want to make sure they're also reflected in the next version folder.
To use the script, make sure you're in the root of the k6-docs folder and run:
scripts/apply-patch <COMMIT> <SOURCE> <DESTINATION>For example, if you'd like to apply the changes from your last commit, from the docs/sources/next folder to the docs/sources/v0.47.x, you can run:
scripts/apply-patch HEAD~ docs/sources/next docs/sources/v0.47.xOr if you'd like to apply the changes from your previous three commits, you can run:
scripts/apply-patch HEAD~3 docs/sources/next docs/sources/v0.47.xk6 follows the style prescribed in the Grafana Writers' Toolkit, which itself inherits most of its rules from the Google developer documentation style guide.
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.
Refer to Writers' Toolkit, Write documentation for more details about how to write new topics, how to use shortcodes, how to add images, and more.
We use ESLint in the repository to validate code snippets in Markdown files. It checks for things such as valid JavaScript syntax, or that imports are defined.
When writing tutorials, it's common to include code snippets that only contain a few lines, and might not necessarily have all necessary imports or variable declarations. For example, if you try to include this code snippet:
```javascript
export default async function () {
const browser = chromium.launch({ headless: false });
const page = browser.newPage();
}
```You might see the following error when trying to commit the file:
/Users/USERNAME/path/to/file/_index.md
12:19 error 'chromium' is not defined no-undefIn case having a short snippet makes sense for your tutorial, you can disable ESLint for a code snippet by using the eslint-skip rule:
<!-- eslint-skip -->
```javascript
export default async function () {
const browser = chromium.launch({ headless: false });
const page = browser.newPage();
}
```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 will sync the changes with the grafana/website repository, and the changes will be deployed to production soon after.
Versions follow the same major numbers as github.com/grafana/k6.
When a new major version of k6 is released, you need to create a new folder for it in the docs/sources folder.
The process for creating a new release should be:
- Review any open PRs that relate to the next major release, and merge them if they have been reviewed and approved.
git pullthe latest version of the k6-docs repository.- In the
docs/sourcesfolder:- Duplicate the
nextfolder. - Rename the
next copyfolder to match the next major release version. For example, if the next release isv0.48, the folder should be renamed tov0.48.x.
- Duplicate the
- Build the docs locally to check that the latest version matches the new version folder.
- Commit and push your changes.
Once your changes are automatically deployed, you should be able to see the new version live by going to https://grafana.com/docs/k6/latest/.