Skip to content

Editing the GLAM Workbench documentation

The code for the GLAM Workbench documentation site (that's the site you're using right now) is all available from GitHub. You're very welcome to submit changes or additions.

If you haven't already, you'll need to set up a free account on GitHub.

Quick fixes

You can edit any page in the GLAM Workbench documentation just by clicking on the pencil icon. You'll find it to the right of the page title.

  • Click on the pencil icon to open the page for editing on GitHub.
  • Follow these instructions to enter, preview, and save your suggested changes.

When you click on the pencil icon, GitHub automatically creates a copy of the repository in your own account. Once you've finished making your changes it'll prompt you to create a pull request, to feed the changes back to the main GLAM Workbench repository. Each pull request is reviewed before the changes go live.

Other minor changes

If you're making changes to multiple pages, you might want to separate the process out into its different stages:

Major changes

If you're making major changes, such as adding a new section, you'll want to set up your own local version of the documentation for editing and testing:

  • Fork the repository.
  • Clone the forked repository to your own computer.
  • Create and activate a Python virtual environment. I use pyenv and pyenv-virtualenv to create and manage Python versions and environments.
  • Move to the site directory: on the command line run cd glam-workbench.github.io/site
  • Install pip-tools: on the command line run pip install pip tools
  • Install requirements: on the command line run pip-sync
  • Start the documentation site: on the command line run mkdocs serve. The site will be available at http://127.0.0.1:8000/.
  • Create or edit pages in the docs directory. See MkDocs and Material for MkDocs documentation for more information.

Any changes to markdown files in the docs directory should trigger a rebuild and reload of the site. If you make changes to templates, or to the mkdocs.yml config file, you'll probably need to stop and restart the server. Once you've finished you can git push the changes back to your fork, and create a pull request.

Note that the main site is built using Material for MkDocs Insiders which is a private repository that can only be accessed through sponsorship. The instructions above will install the public version of Material for MkDocs. The site will look and act much the same, but some extended features, such as search and tagging won't be available.

Contributors

Contributors will be listed on the site's contributors page.