MkDocs Static Site

A Tugboat Preview for a MkDocs static site builds the static site within the Tugboat environment, and then serves it. This config generates a static site that looks like your site directory when you mkdocs build, which should be the same thing you see in your local development environment when you run mkdocs serve. However, the Tugboat Preview version of your MkDocs site is accessible via the secure Tugboat URL by anyone who has the link; no need for the viewer to have a local environment.

Configure Tugboat

The Tugboat configuration is managed by a YAML file at .tugboat/config.yml in the git repository. Here’s a basic MkDocs static site configuration you can use as a starting point, with comments to explain what’s going on:

  # What to call the service hosting the site. Because there is only
  # one service, it is automatically set as the default service, which
  # does a few things
  #   1. Clones your mkdocs git repository into the service container
  #   2. Exposes port 80 to the Tugboat HTTP proxy
  #   3. Routes requests to the preview URL to this service
    # Use the available version of Apache by not specifying a version
    image: tugboatqa/httpd

    # A set of commands to run while building this service
      # Commands that set up the basic preview infrastructure
        # Use apt-get to download mkdocs into the Apache service
        - apt-get update
        - apt-get install -y mkdocs
        # Clean up apt artifacts to keep the Preview small
        - apt-get clean
        - rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

        # Use the mkdocs command to build your static site
        - mkdocs build

        # Link the document root to the expected path. This example links the
        # /site directory generated by the mkdocs build to the docroot
        - ln -snf "${TUGBOAT_ROOT}/site" "${DOCROOT}"

Want to know more about something mentioned in the comments of this config file? Check out these topics:

Start Building Previews!

Once this Tugboat configuration file is committed to your git repository, you can start building previews!