This repository contains the source files for jenkins-x.io
NOTE: Please browse these docs on jenkins-x.io. Not all links work when browsing the Markdown files inside this repository.
To edit the docs locally, you need to clone this repository:
git clone --recurse-submodules --depth 1 https://github.com/jenkins-x/jx-docs.gitNotice the use of --recurse-submodules in the clone command above.
This option will pull in two git submodules, namely
docsy and labs-enhancements.
If you already have a git clone without the submodules checked out you can run:
git submodule update --init --recursiveIn subsequent updates of the sources via git pull also remember to pull the changes from the submodules:
git pull --recurse-submodulesyou can view the commit sha of the sub-modules via:
git submodule status --recursiveAfter getting all the sources, you need to install npm and make sure the required npm modules are installed:
npm installThe site itself is built with Hugo and configured in config.toml.
You have two options to run Hugo, either directly on your machine or via Docker Compose.
The following two sections describe the two alternatives in more detail.
NOTE: Hugo renders the site in memory in development mode. Per default, no content is written to disk.
If you want to build the site locally on your machine, you need to install Hugo. Check the Makefile for the latest recommended version use and check whether the environment variables of Golang are set. Set the env variable HUGO_GH_ACCESS_TOKEN to a github token that can read from jenkins-x/jx repo to allow the contributors plugin to run.
Once installed, you can run:
make serverYou can now access the site under localhost:1313.
Instead of installing Hugo locally, you can use the provided docker-compose.yml to spin up the Hugo server in a containerized environment.
Make sure you have Docker installed.
make compose-upYou can now access the site under localhost:1313. The Hugo server is running in the background. You can stop it via:
make compose-downWe are not all masters of spelling, so luckily there are tools to help us fix that. We are using node-markdown-spellcheck to run through all our markdown files and list any spelling issue or unknown word.
To make this as simple as possible, just run the following command:
make spellcheckThe report likely includes words that are spelt correctly, but that just means the spell checker is not aware of the correct spelling (happens a lot for technical terms, commands, etc.).
Please edit .spelling and add the unknown word.
Also, please try and keep the list alphabetically sorted, which makes it easier to navigate.
To get help in checking all the links, we'll use htmlproofer.
make linkcheckNOTE: The initial run is really slow (due to external link checks) and that the cache is only build up when it finishes.
NOTE:: It's safe to ignore the ... x509: certificate ... errors for now
If you move a page to a different location you can add a redirect via using an aliases entry in the header of the page:
aliases:
- /some/old/path
- /another/pathTo upgrade to a new enhancements commit - we'll hopefully automate this soon!
cd content/en/docs/labs/enhancements
git checkout master
git pull
cd ..
git add enhancements
git commit -m "move to latest enhancements"Docsy is added to the jx-docs repository as a submodule under the themes directory. To update docsy, run the following commands:
cd themes/docsy
git pull origin master
git submodule update --init --recursiveTo let more people know Jenkins X better, localization is essential and meaningful. And we should keep some rules about this, please read related languages below:
Please refer to the documentation contributing guide available at Jenkins X website.