Editing these docs
Editing these docs
Section titled “Editing these docs”You don’t need any special software to improve these pages — just a browser and a GitLab login. Here’s the whole process.
Fixing wording on a page
Section titled “Fixing wording on a page”- Open the page you want to change on this site.
- Click “Edit page” (bottom of the page). It opens the exact source file in GitLab’s editor.
- Make your changes. The text is Markdown — mostly just normal writing. See the cheatsheet below.
- At the bottom, type a short note (“fix typo in ingest section”), choose “Start a new branch”, and click Commit. GitLab offers to open a merge request — accept it.
- That’s it. The change is checked automatically and a colleague merges it. The site updates on the next publish.
You can’t break the live site by editing — nothing goes live until the merge request is reviewed and merged.
What you can and can’t edit
Section titled “What you can and can’t edit”| You see… | Can you edit it here? |
|---|---|
| A normal page with an “Edit page” link | Yes — that’s the source; edit away. |
| A page with an orange “Generated reference — please don’t edit” box | No. It’s built automatically from a data file. Editing here would be overwritten. Tell a maintainer what’s wrong and they’ll fix the source. |
| Diagrams | These are generated from code. Note what’s wrong and a maintainer will regenerate them. |
The rule of thumb: if a page has an “Edit page” link, it’s yours to edit. If it doesn’t, it’s generated.
The top of a page (frontmatter)
Section titled “The top of a page (frontmatter)”Every page starts with a block between --- lines (the title, a summary, etc.).
You can edit the wording of the title and summary, but please keep the
--- lines and the field names (like title:) intact — that block tells the
site how to display the page.
Markdown in 30 seconds
Section titled “Markdown in 30 seconds”**bold**→ bold,*italic*→ italic## A heading— start a line with##for a section heading- a point— start a line with a dash and a space for a bullet list[link text](https://example.com)— a link- Leave a blank line between paragraphs.
That’s genuinely most of it. When in doubt, copy the style of the text already on the page.
Previewing your change
Section titled “Previewing your change”You don’t have to preview — the maintainer will check it in the merge request. If you’d like to see it first, ask a maintainer to open the branch in the preview site.