HTML Ruby Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Docs Like Code

The Website

This website is intended to offer stories and articles about how to treat docs like code, and lessons learned along the way. You are welcome to tell your story here as well.

To Contribute

You can directly submit a pull request using the fork-and-pull workflow to add an article, or submit to the justwriteclick/docs-like-code-stories repo if you want to follow a question-and-answer template.

Pushing to the build branch lets you preview the build output using Netlify. You must log into Netlify to view the preview deploy.

Pushing to the master branch builds output to using Netlify. Auto publishing is on as a setting in Netlify, so deploys from master are published automatically.

Theme Colophon

Theme courtesy of

To Build Locally (MacOS)

Test your additions and changes to content by running a local build.

To prepare your environment to build locally, you need to install brew,, and Ruby version manager:

  1. Use brew to install a Ruby version manager.

    $ brew install rbenv ruby-build
  2. Add rbenv to bash so that it loads every time you open a terminal.

    $ echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
  3. Source your .bash_profile file.

    $ source ~/.bash_profile
  4. Install the version Ruby we need:

    $ rbenv install 2.3.1
    $ rbenv global 2.3.1
    $ ruby -v
  5. Run gem install bundle to install the bundler gem, which helps with Ruby dependencies.

  6. Run bundle install the first time you are in the docslikecode directory.

To build locally: Once you have completed preparing your environment, then you can build locally and review the site in your browser.

  1. Run the serve command.

    $ bundle exec jekyll serve
  2. Use the Server address URL in a browser to preview the content.

  3. Press Ctrl+C in the serve terminal to stop the server.

Leave the serve terminal open and running. Every time you save changes to a file, it automatically regenerates the site so you can test the output immediately. The only file where changes require a restart is the _config.yml file.

To Build Locally (Docker)

  1. Install Docker Community Version.

  2. In the root directory where the docslikecode repo is cloned, create a file named Dockerfile containing:

FROM grahamc/jekyll:latest

# Install whatever is in your Gemfile
ADD Gemfile /tmp/
ADD Gemfile.lock /tmp/
RUN bundle install

# Change back to the Jekyll site directory

  1. Create a file, also in the root directory, containing the following:
# Develop override settings
# Use when building with Docker container and script locally

url                      :

# Analytics
  provider               : false
  1. Create a file, also in the root directory, containing the following:
#!/usr/bin/env bash

# Set to the name of the Docker machine you want to use

# Set to the name of the Docker image you want to use

# Stop on first error
set -e

# Create a Docker host
if !(docker-machine ls | grep "^$DOCKER_MACHINE_NAME "); then
  docker-machine create --driver virtualbox $DOCKER_MACHINE_NAME

  # Start the host
  if (docker-machine ls | grep "^$DOCKER_MACHINE_NAME .* Stopped"); then
    docker-machine start $DOCKER_MACHINE_NAME

    # Load your Docker host's environment variables
    eval $(docker-machine env $DOCKER_MACHINE_NAME)

    if [ -e Dockerfile ]; then
      # Build a custom Docker image that has custom Jekyll plug-ins installed
        docker build --tag $DOCKER_IMAGE_NAME --file Dockerfile .

	  # Remove dangling images from previous runs
	    docker rmi -f $(docker images --filter "dangling=true" -q) > /dev/null 2>&1 || true
	      # Use an existing Jekyll Docker image

		echo "***********************************************************"
		echo "  Your site will be available at http://$(docker-machine ip $DOCKER_MACHINE_NAME):4000"
		echo "***********************************************************"

		# Start Jekyll and watch for changes
		docker run --rm \
		  -e JEKYLL_ENV=production \
		  --volume=/$(pwd):/src \
		    --publish 4000:4000 \
		       serve --watch --drafts --force_polling -H
  1. If using Windows, launch Git Bash to run the file. If using MacOS, launch a Terminal window to run the file. Make sure to allow permissions to execute the file, for example chmod 600
$ ./