Contributing to these docs

These docs are a community effort and contributions are very welcome — from fixing a typo to writing a whole new section.

What's the difference between the Technical docs and individual module and theme docs?

This documentation is general documentation that covers the LocalGov Drupal technical ecosystem as a whole. It also aims to answer frequently asked questions and burning topics. Detailed technical documentation about a feature can be included in the docs of the individual modules and themes. In time, we hope to link to and from these general technical docs to those detailed project docs.

Create a work item

Start by creating a work item describing the task: what needs amending, adding or removing, and why. If you can, include your suggested text in the work item itself — or go one better and create a merge request with the suggested changes.

Work items, issue forks and merge requests are all covered in the LocalGov Drupal Ladder. This project is currently one of the few still using the old-style drupal.org issue queue, and the ladder covers that too.

Contributing changes

To contribute changes, work on an issue fork and open a merge request, as described in Issues, issue forks and merge requests.

See your changes locally

The site is built with MkDocs using the Material theme. To preview your changes, you'll need Python, then install the theme and the navigation plugin:

pip3 install mkdocs-material mkdocs-awesome-pages-plugin

Then, from the project root:

mkdocs serve

This serves the site at http://127.0.0.1:8000 and reloads automatically as you edit.

Where the content lives

All pages live in the docs folder. Each section is a folder, and each page is a markdown .md file — create a new file and it becomes a new page. The first heading in the file (or a title in the frontmatter) becomes the page title in the navigation.

The order of pages within a folder is controlled by a .pages file in that folder:

arrange:
  - index.md
  - first-page.md
  - second-page.md
  - a-sub-folder

List the files and folders in the order you want them to appear in the navigation. If your new page doesn't show up where you expect, check the .pages file in its folder.