documentation
Documentation for Codeship CI & CD service.
Getting Started
Prerequisites
We recommend using Docker to build and test the documentation. Running via Docker is only required if you plan to make changes to the styling or layout of the site.
For content related changes and fixes, it's easiest to use GitHub's File Edit UI to make the changes and create the pull request.
Setup
The first step is cloning and going into the repository.
git clone [email protected]:codeship/documentation.git
cd documentation
Then build the container and save it as a tagged image.
docker build --tag codeship/documentation .
You can now run commands via that container. By default, it will build the site and start the Jekyll development server.
docker run -it --rm -p 4000:4000 -v $(pwd):/docs codeship/documentation
To access the site open http://IP_OF_YOUR_DOCKER_SERVER:4000 in your browser. Usually, this is localhost:4000.
On Windows, the Docker commands are executed via the Docker Quickstart Terminal. If localhost doesn't work, you might have to open a normal command prompt and type docker-machine ls. There you can take the IP that is listed under URL and type the IP (with port 4000) into your browser to reach the documentation.
Development
Updating dependencies
To update Rubygem based dependencies, update the Gemfile (if required) and run
docker run -it --rm -v $(pwd):/docs codeship/documentation bundle lock --update
For NPM based dependencies, run the following two commands
docker run -it --rm -v $(pwd):/docs codeship/documentation yarn upgrade
Spellcheck
To run spellcheck on all Markdown files, run the following command:
docker run -it --rm -v $(pwd):/docs codeship/documentation yarn run check
To run the interactive correction functionality and to update the .spelling file, run:
docker run -it --rm -v $(pwd):/docs codeship/documentation yarn run fix
See output and mdspell for details on how to maintain the .spelling file.
Linting
SCSS
SCSS files are automatically linted using scss-lint. To run it, execute the following command
docker run -it --rm -v $(pwd):/docs codeship/documentation bundle exec scss-lint
It's configured in .scss-lint.yml and the default configuration is available online as well.
JSON
docker run -it --rm -v $(pwd):/docs codeship/documentation gulp lint
Jekyll
docker run -it --rm -v $(pwd):/docs codeship/documentation bundle exec jekyll doctor
Markup
Table of contents
If you want to include a table of contents, include the following snippet in the markdown file
* include a table of contents
{:toc}
URL Helpers
Tags
Generate a URL for the specified tag (database in the example below). This function is also available as a filter and can be used with a variable (tag in the example).
{% tag_url databases %}
{{ tag | tag_url }}
generates the output as follows (depending on configuration values):
/tags/databases/
Man Pages
Link to a particular Ubuntu man page. The Ubuntu version currently defaults to Ubuntu Bionic.
{% man_url formatdb %}
generates the following output:
http://manpages.ubuntu.com/manpages/bionic/en/man1/formatdb.1.html
Notes
You can include note sections on the pages via the csnote helper. Those blocks are powered by the Shipyard Notes component
{% csnote info %}
Some informational text.
{% endcsnote %}
As an optional argument you can specify either info, success or warning. If you don't specify the argument a default (grey) note will be used.
