/jx-docs

Source code used to build the Jenkins X documentation and website

Primary LanguageHTMLApache License 2.0Apache-2.0

Jenkins X Docs

This repository contains the source 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.

Building the docs

Preparing the sources

To edit the docs locally, you need to clone this repository:

git clone  --recurse-submodules --depth 1 https://github.com/jenkins-x/jx-docs.git

Git submodules

Notice 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 --recursive

In subsequent updates of the sources via git pull also remember to pull the changes from the submodules:

git pull --recurse-submodules

you can view the commit sha of the sub-modules via:

git submodule status --recursive

Downloading npm modules

After getting all the sources, you need to install npm and make sure the required npm modules are installed:

npm install

Running Hugo

The 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.

Locally

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. Once installed, you can run:

make server

You can now access the site under localhost:1313.

Dockerized

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-up

You can now access the site under localhost:1313. The Hugo server is running in the background. You can stop it via:

make compose-down

Common Workflows

Running spell check

We 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 spellcheck

The 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.

Checking links, images, etc

To get help in checking all the links, we'll use htmlproofer.

make linkcheck

NOTE: 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

Adding redirects

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/path

Upgrading the enhancements content

To 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"

Localization

To 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:

Contributing

Please refer to the documentation contributing guide available at Jenkins X website.