Git Sync
How Markdown files become docs
Git Sync reads every .md, .mdx and .markdown file in your docs folder. Your repository's structure becomes your knowledge base's structure, so you can organise docs the way you already do in Git.
Folders become categories
Sub-folders become categories, and a number at the start of a name sets the order. Files at the top of the docs folder go into a General category.
Repository
- docs
- 01-getting-startedthe "Getting started" category
- 01-install.mdfirst doc in the category
- 02-first-ticket.md
- img
- inbox.pngcopied to your media library
- guides
- reports.md
- overview.mdtop level: the General category
- _draftsfolders starting with _ or . are ignored
Titles, links and images
| What | How Git Sync handles it |
|---|---|
| Title | title in the front matter, else the first # Heading, else the file name |
| Links between files | ../guides/reports.md becomes a link to that doc, and turns back into a relative link when the doc is pushed |
| Links to other files | Open the file on GitHub or GitLab |
| Images | Images next to your files are copied into the media library once |
Callouts become alerts
GitHub alerts and MkDocs admonitions become PinkDocs alerts, so docs written for another tool look right without changes.
> [!WARNING]
> Back up your database before upgrading.
Both become this:
Back up first
Back up your database before upgrading.
PinkDocs blocks written as directives, such as :::alert and :::steps, work in files too.
Front matter
Front matter from Docusaurus, MkDocs, Hugo and Jekyll is understood. Docs pushed from WordPress get front matter like this:
—
title: Install the plugin
description: How to install PinkDocs on WordPress
tags: [setup, install]
order: 1
pinkdocs_id: 412
—
| Key | What it does |
|---|---|
title | The doc title |
description, excerpt or summary | The excerpt shown in lists and search |
category | Category slug path, such as getting-started/install, when it differs from the folder |
tags | Doc tags |
order, sidebar_position, nav_order or weight | Position in the sidebar |
draft: true | Keeps the doc as a draft |
slug | The doc's URL slug |
pinkdocs_id | Links the file to its doc, so a file you move and edit in one commit stays the same doc |
Blocks Markdown can’t express
WordPress blocks with no Markdown equivalent are kept as block markup in the file, so pushing a doc and pulling it back changes nothing.
Was this page helpful?
Great! What worked best for you?
Please provide additional details about your experience.
Thank you for your feedback!
We appreciate your input.
