Create a basic docs site

This documentation page should help you create a basic documentation site using the same styling and feature as the starter kit documentation you are currently reading.

In the following you'll be creating a git repo, adding the basic documentation structure, adding some Lando configuration to view the documentation locally and, finally, adding some GitLab CI configuration to automatically build and deploy the documentation site.

Creating a new site

All documentation sites need to live in git repository in GitLab so the first thing to do is create a new git repo for the site. Agile Collective have a dedicated docs group for our documentation sites. This already includes configuration for creating sites, making things easier later on, so create a new repo in this group unless there's a good reason not to.

All the documentation will live in a docs directory in the git repo. This will contain a number of Markdown files which can be organised into a single level of directories. Nesting directories inside the docs directory beyond a single level is not currently supported. Each directory should have an index.md file.

You can read more about the structure of the docs directory in the structuring the docs documentation for content editors. There's more information on writing Markdown in the Markdown reference guide.

Inside docs you'll need to create _data directory and within this a site.yml file. This file contains metadata about the site. The minimum it should contain a title and a site_url. For example:

##
# Site info.
---
##
# Site title.
title: Agile Collective documentation starter kit

##
# Canonical site URL.
site_url: https://starterkit.docs.agile.coop

You can read more about adding metadata to a site on the metadata and frontmatter page.

Viewing the site locally

To see changes to the site before changes are committed and pushed to the git repo it's possible to use Lando.

Create a new file in the root of the git repository called .lando.yml with following content:

name: {SITE_ID}
proxy:
  starter-kit:
    - {SITE_ID}.lndo.site:8080
services:
  starter-kit:
    type: node
    overrides:
      image: gitlab.agile.coop:5050/docs/11ty-docs-starter-kit:base
    build_as_root:
      - chown -R node:node /build
    scanner: false
events:
  pre-start:
    - starter-kit: cd /build && npm install
tooling:
  11ty:
    service: starter-kit
    cmd: cd /build && npm run start:lando
  update-docs:
    service: starter-kit
    cmd: rsync -av /app/docs/ /build/docs/

Replace {SITE_ID} is a unique name for the site.

The docs site can then be viewed with:

lando start
lando update-docs
lando 11ty

Due to limitations with the Docker images used by Lando the docs aren't directly served by Lando and so it's necessary to run the the lando update-docs command whenever there are changes to view.

Deploy site using GitLab CI

Once you have some content in your new site it can be automatically created and updated whenever changes are pushed to the GitLab repo. For this you'll need to add a .gitlab-ci.yml file in the git root with the following:

##
# Build docs using 11ty starter kit.
---
include: https://gitlab.agile.coop/docs/11ty-docs-starter-kit/-/raw/1.x/.gitlab-ci/build-deploy-docs-images.yml

variables:
  SITE_ID: { SITE_ID }

Replace {SITE_ID} with a unique name for the site.

After an initial git push it will take a few minutes for everything to run. Assuming everything is setup correctly, your new docs site will be available at https://{SITE_ID}.docs.agile.coop/.

There are a number of options to customise the deployment, including changing the base URL from docs.agile.coop, which are discussed in deployment variables.

If your docs site is not in the GitLab docs group then you'll need to configure the GitLab project.

Last updated: