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.
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:
- Fork the documentation repository.
- Make changes using the GitHub file editor.
- Create a pull request to share your changes back with the main repository.
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
sitedirectory: on the command line run
pip-tools: on the command line run
pip install pip tools
- Install requirements: on the command line run
- 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
docsdirectory. 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 will be listed on the site's contributors page.