54. Documentation Overview¶
This document describes the easiest workflow for editing documentation.
Requirements:
- You need to have a GitHub account and be logged in to your account
- You need to have been given access to the repo by the repo manager
54.1 General Workflow¶
- Go to the repo for the documentation.
- Press the
.
key on your keyboard. - Select a file under the src folder to edit
- Press Ctrl-S to save your work.
- Go to the Source Control tab to commit your work.
- Add a short, descriptive comment describing your changes.
- Press the
Commit and push
button. - Wait a few minutes and your changes should be published live.
54.2 Adding a new page¶
Any new page you create needs to be also added to mkdocs-base.yml
so that it gets 'built.
If you wish to build a page but not have it in the menu system, you can give it a blank menu description e.g.
# Pages to render but exclude from navigation
- "": developer/guide/templates/pull-request-template.md
Conversely, to ensure it is shown in the menu, find the right place in the navigation tree and then insert it with a short descriptor. e.g.
54.3 Adding images¶
You can easily upload images into the documentation sources and then add them to your document.
- Take an image using your favourite screenshot tool.
- Using your file manager, drag the file from your desktop into the img folder in the relevant part of the documentation you are working on.
Shift+Drag
the image into your markdown document.- Edit the image description (the part in square brackets)
54.4 Adding links¶
You can add a link to any text by doing the following:
- Copy the link from your web browser to your clipboard.
- Either 2.1 Past the link directly into the document sources. 2.2 or, write some words ine square brackets and paste the link in round brackets after, VSCode will create a markdown formatted link.
This is a normal link https://staging-geosight.unitst.org/, this is a link.
The above in markdown:
This is a normal link https://staging-geosight.unitst.org/, [this is a link](https://staging-geosight.unitst.org/).
54.5 Page previews¶
You can easily preview the page you are working on by doing this:
- Press
Ctl-Shift-V
to open a preview of the page you are currently working in. - Drag and drop the preview tab to the right side of the editing environment for a side-by-side view.
54.6 Leaving the editor viewer¶
How to leave the interactive editor.
- Click the 'hamburger' menu and go to the repository.
- Wait a few moments and the 'normal' GitHub page will load.