Editing the docs online

✏️ Editing the docs online

Fix or write a docs page in your browser. Nothing to install, nothing to host.

Every save is a Git commit with your name, and changes are reviewed before they reach the website.

---

🧭 Pick your tool

	🖋️ Pages CMS	🐙 GitHub web editor	💻 github.dev / your own editor
Best for	Writers, most edits	A typo, one line	Many pages at once, developers
Looks like	A form and a word-processor editor	A plain text box	VS Code, in the browser or on your PC
Installs	None	None	None (github.dev) · Git + editor (local)
WYSIWYG	✅ Text, headings, lists, tables, images	❌ Preview tab	🟡 Preview beside the text
Drag and drop images	✅ Into the page; the image bot files them	🟡 Uploads go to GitHub, not the library	🟡 Copy the file into docs2/images/_inbox/
Insert a tip, image, table	✅ / menu	❌ Type it	❌ Type it
Review	Saves to your own branch (master is protected); you open the pull request	✅ Opens a pull request for you	✅ Your own pull request
Open it	Edit the docs	✏️ pencil on any file	Press . on the repo page
Verdict	⭐ The advertised way	Typos	Bulk and developer work

On the website, every page has Edit this page at the bottom: it opens that exact file in GitHub's editor, and Propose changes makes the branch and pull request for you.

---

🖋️ Pages CMS (recommended)

🔑 One-time setup (maintainer)

1. Push the docs branch to GitHub.
2. Open app.pagescms.org, sign in with GitHub, and install the Pages CMS GitHub App on Bforartists/Manual only.
3. Pages CMS reads .pages.yml in the repository root: the page tree, the form, the image library and the commit messages.

✍️ Writing a page

1. Click Edit the docs above and sign in with your GitHub account.
2. In the branch menu at the top, create a branch for your change, for example docs/fix-timeline. master is protected, so saves go to your branch.
3. Open 📘 Documentation pages. Pages are shown as a tree, like the sidebar.
4. Change the form at the top (title, status, video, shared sections) and the text below.
5. Press / on an empty line for the menu: headings, lists, Image, Table, Quote.
6. Drag a screenshot into the page. It lands in the image library and the image bot files it.
7. Click Save (top right). Pages CMS commits your change with your name.
8. Check your change: on GitHub, the newest commit on your branch is docs: update … (Pages CMS, your name). Only your lines should be green.
9. On GitHub, open a pull request from your branch into master. Checks and a 👀 preview link follow.

📁 New chapters and sub-chapters

To make	Do this in Pages CMS
📄 A page	In a section folder, Add an entry, give it a title, Save
📁 A chapter with sub-chapters	Create folder (my-chapter), then Add an entry inside it with the file name index.md
↳ A sub-chapter	Add an entry inside the chapter folder

You only type the title. The bot fills in the page ID, section and breadcrumb after you save.

💡 Plain writing: no codes to learn

To get	Do this
💡 A tip or note	/ → Quote, then start with Tip: (or Note:, Warning:, Important:)
⌨️ Keycaps	Type Ctrl + S
🧭 A menu path	Type Edit › Preferences (copy the ›)
🖼️ A screenshot	Drag it in, or / → Image
🎬 A video	Paste a YouTube link on its own line, or use the Chapter video field
♻️ A shared section	Pick it in Shared sections on this page; edit its text in ♻️ Shared snippets

More: Plain writing.

🤖 Your pull request opens by itself

Save your edits to a branch named docs2/edit/<your-topic> (in Pages CMS, use the branch menu to create it). The first save opens the pull request into master automatically, and the preview and checks follow in a comment. Every further save on that branch updates the same pull request.

One-time setting for the maintainer: Settings → Actions → General → Workflow permissions → tick "Allow GitHub Actions to create and approve pull requests".

⚠️ Good to know

	What happens	What to do
🧹	The editor writes pages in its own tidy style	Nothing. The converter writes the same style, so your save only changes your lines
>	A plain > is saved as >	Use › for menu paths
🖼️	Alt text of a dropped image is its file name	Change it to what the image shows, or the bot uses the heading above it

---

🐙 GitHub web editor

Open a page on GitHub and click the ✏️ pencil. Edit, then Commit changes → Propose changes. GitHub makes a branch and a pull request for you. Good for a typo.

💻 github.dev or your own editor

Press . on the repository page: VS Code opens in your browser. Open a page, press Ctrl+K V for a preview, commit from Source Control to your own branch, then open a pull request. Locally the same works with Git and any editor.

---

🔍 After you save

1. A pull request shows the change. Checks run: front matter, links, images, no lost words.
2. 👀 A bot comment links to a preview of the page with the website's styles.
3. The section reviewer approves. After merge, the page syncs to the website's staging site. Going live is a maintainer's click.

See Branches and review and Checks and previews.