10 quick tips to improve your technical writing workflow in GitBook
10 practical GitBook tips for technical writers to ship better docs faster — including Markdown, keyboard shortcuts, integrations, Git Sync and more
Last updated
Was this helpful?
10 practical GitBook tips for technical writers to ship better docs faster — including Markdown, keyboard shortcuts, integrations, Git Sync and more
Last updated
Was this helpful?
Was this helpful?
Your technical documentation probably already contains the right information. Nice work! Now it’s time to make it faster to maintain and easier to consume.
And with GitBook, there are a few simple ways to improve your workflow and speed things up. That includes links, blocks, and two-way sync with GitHub or GitLab.
This post shares 10 tips you can apply today. Each one saves time and improves clarity.
Use Markdown and keyboard shortcuts to write faster.
Use / to add blocks and inline content without leaving the keyboard.
Use relative links, descriptive captions, and alt text for accessibility and crawlability.
Use GitBook Agent for writing and reviewing.
Add integrations to bring your tooling into your docs.
Use Git Sync to keep docs and repos aligned, in both directions.
Yes, you can certainly write into the GitBook editor in plain text. But it also supports Markdown as a keyboard-friendly way to format your content and add blocks fast.
GitBook supports basic formatting, including bold and italic. But you can also add H1, H2 and H3 titles using hashes (#) at the start of a new block, add code and quote blocks, and create lists with a few keystrokes.
New to Markdown? We’ve got your back. Many other tools outside GitBook support it — so learning it now will likely prove useful in other places. You can learn more about our Markdown support in our documentation, and explore Markdown itself in more detail over at CommonMark.
Okay, so you’re a Markdown master. In that case, here are some quick keyboard shortcuts that will speed up the tiny tasks you carry out multiple times every day. Below, we’ve chosen a few of our most-used shortcuts to get you started. You can head to our documentation to explore the full list.
⌘ + K (Mac) or Ctrl + K (Windows) — Open the Ask or search panel
⌘ + Enter (Mac) or Ctrl + Enter (Windows) — Exit from content block (code, tabs, table, quote, etc)
Esc — Select the entire active block (or multiple active blocks)
⌘ + ⌥ + 0 / 1 / 2 /3 — Turn text into a paragraph/heading 1/heading 2/heading 3 block
There’s one keyboard shortcut we didn’t list above, because we think it’s important enough to deserve its own section. Hitting / opens the block-insert palette — and unlocks a whole selection of possibilities for your content.
Use it on a new, empty block and you can select from the full list of blocks in GitBook, plus any integrations you’ve added. You can scroll through the list, or type to narrow it down.
Alternatively, use ⌘ + / or Ctrl + / on a block you’re editing — whatever its type. This opens a context menu for that block.
In a text block, you can switch between paragraph and heading. In a code block, you can set syntax, add line numbers, and more.
Try it on different blocks and explore the options. It’s one of the fastest ways to edit in GitBook.
Using the block-insert palette isn’t the only way to add content to your pages fast, though. When typing in a text block, you can hit / at any time to open the inline palette.
The inline palette lets you add an image, button, emoji, link, math & TeX, icon or expression. It’s the fastest way to add common elements without context switching.
One shortcut we did list above, but bears repeating, is the option to select a whole block or blocks — simply by hitting the Esc key. This is great for reorganizing content within your page, as you can drag multiple blocks around at once, or use commands like cut, copy, paste and delete to manage your content.
GitBook includes a built-in AI Agent that can write content for you based on a prompt — or review your changes before they go live.
The best part? The Agent can understand and follow your style guide. So not only does it find and fix spelling and grammar mistakes — it can also tell you when you’ve deviated from your standard style.
You can open a chat with the GitBook Agent in any change request by hitting the GitBook Agent 
button in the space header bar, or open a comment and tagging @gitbook to call it.
And to get the Agent to review your work, click Request a review and simply add the Agent as a reviewer — it’ll comment on your page directly.
Relative links in GitBook are the best way to link to other parts of your documentation. Why? Because if someone changes the URL, name, or location of the linked content, GitBook will still keep its reference up to date. And that means fewer broken links — and better documentation SEO and AI optimization.
If your technical documentation is published, you can link to anchors, other pages or even other sections on your docs site.
You add them like any other link. Highlight the text, click the link button on the inline palette, or hit ⌘ + K / Ctrl + K. Then type the name of the anchor, page, or space you want to link to.
We’re sure you know that hint blocks have four different colors and styles that you can choose from, to match the kind of content inside. What you may not know is that you can quickly cycle through the different styles simply by clicking the icon in the block itself. There are four to choose from — and it saves you opening the menu to change it!
While there are plenty of built-in tools that will make your life with GitBook easier, you shouldn’t stop there. We have a whole host of integrations that you can add to improve your workflows — and your technical documentation.
From adding extra analytics tools to embedding Linear issues, Mermaid diagrams and RunKit notebooks, you’ll find plenty of ways to supercharge your technical docs and get extra features with just a few clicks.
Take a look at all our integrations, and see how you can build your own.
This last entry is a big one — and if you haven‘t set it up already, it could save you hours of work in the long-run.
Git Sync lets technical teams synchronize GitHub or GitLab repositories with GitBook — and turn existing Markdown files into beautiful, user-friendly technical documentation. And when you edit that content in GitBook, Git Sync will automatically update your codebase in GitHub or GitLab to keep everything in sync.
Best of all, Git Sync is two-way — so if you merge a pull request in GitHub or GitLab, that change will also appear automatically in GitBook. How handy is that?
Once you’ve set up the sync, your whole team can contribute to your technical documentation — and your wider knowledge base — no matter which tool they prefer to use.
Find out how to get set up in our documentation.
Use Markdown for headings, lists, code, and emphasis. Pair it with keyboard shortcuts for repeat actions.
Type / on a new line to open the block insert menu. Use ⌘ + / or Ctrl + / to edit the current block type.
Use relative links for anything inside GitBook. They stay valid when pages move or get renamed.
Use descriptive headings, short sections, and explicit definitions. Add alt text and captions for images.
Use Git Sync for two-way sync with GitHub or GitLab. That keeps Markdown and GitBook content aligned.
→ How to use SEO techniques to improve your documentation
→ GEO guide: How to optimize your docs for AI search and LLM ingestion