# GitBook documentation
Create and publish AI-native documentation your users will love. GitBook gives you intelligent tools to build product guides, API references, and documentation that improves over time.
## Documentation your users actually read
Your users are humans and their AI agents — GitBook publishes for both. Write in the editor, drive it from your agent, or sync from Git.
QuickstartGitBook MCP
How do you want to work?
The same docs, three ways in. Most teams use more than one.
:hand-pointer:
In the editor
Write and publish visually. Blocks, change requests, and review without touching a terminal.
# Quickstart
Get up and running in GitBook and publish your first docs site in minutes
This quickstart guide explains how to get set up in GitBook and publish your first docs site in minutes.
At the end of this guide, you’ll have a live documentation site, ready to expand and customize.
{% stepper %}
{% step %}
#### Create your account
[Create an account](https://app.gitbook.com/join) to get started with your first documentation site.
{% endstep %}
{% step %}
#### Create your first site
1. From your organization **Home**, click the **+** next to **Sites** in the sidebar.
2. Give your site a name your visitors will recognize.
3. Click **Create**.
{% endstep %}
{% step %}
#### Choose how you want to start
GitBook welcomes you to your new site and asks how you'd like to begin.
Starting point
Best for
Docs template
Starting from a ready-made documentation layout with placeholder sections — the fastest way to see a full site working.
Import
Bringing in existing content from online docs, Markdown, or HTML.
OpenAPI
Generating interactive API reference docs from an OpenAPI spec.
Blank
Starting from an empty section and building from scratch.
Sync with Git
Keeping your docs in sync with a GitHub or GitLab repository.
Or, you can pick from your organization's existing content if you already have some work in GitBook.
This guide follows the template path:
1. Click **Docs template** and review the preview.
2. Click **Use Docs Template** to apply it.
{% endstep %}
{% step %}
#### Explore your new site
Your site opens unpublished, so you can edit, customize, and preview everything before it goes live. The sidebar shows:
Sidebar area
What you'll find
Site header
Your site name, its publish status, and the Preview and Publish buttons.
General
Overview, Change requests, Site structure, and Settings.
Tools
Styleguide, Customize, Analyze, and Extend.
Content
These are your site's sections - for the Docs template: Home, Documentation, API Reference, Changelog, and Help Center. Use the icons on the Content header to find, rename, and add sections.
{% hint style="success" %}
Your content isn't published yet — so you can edit, customize, and preview your docs site before making it live. Click **Publish** to make it live immediately.
:arrow-down: [Jump to the 'Publish your documentation' step on this page](#publish-your-documentation)
{% endhint %}
{% endstep %}
{% step %}
#### Edit your content
The Docs template starts you with placeholder sections in the **Content** part of the sidebar. Click any section to open it and see its placeholder content.
There are two ways to edit and update your content in GitBook — in our visual editor, or following a docs-as-code workflow. **You can choose one, or use a combination of both.** Whichever workflow you prefer, you'll edit your content using a **branch-based editing flow**. Find out more on [the Concepts page](/docs/reference/concepts).
{% tabs %}
{% tab title="Visual editor" icon="hand-pointer" %}
GitBook's what-you-see-is-what-you-get (WYSIWYG) editor lets you edit content visually, drag content blocks to reorganize them, and see how your content looks as you work. It's ideal if you don't want to work in a code editor, or you're used to tools like Notion or Google Docs.
**Edit your docs in a change request**
1. In the **Content** section of the sidebar, click a section — such as Documentation — to open it.
2. Click **Edit** in the top-right corner. This opens a change request where you can change the content of the section.
3. Click **Add new…** > **Page** in the table of contents on the left-hand side.
4. Give your new page a title.
**Preview your changes**
Along the top of the web app you'll see tabs for **Editor**, **Changes**, and **Preview**. These switch between different views for your content. Click **Preview** to see how your docs site looks with all the changes in your change request, on both desktop and mobile.
**Merge your changes**
Once you're happy with your changes, click the **Merge** button in the top-right corner. This updates the primary version of your content with all the edits from the change request. If the content is part of a live docs site, the site updates immediately.
{% endtab %}
{% tab title="AI Agent" icon="robot" %}
Sync your documentation with a GitHub or GitLab repository to enable code-based editing in your existing developer environment. It's ideal for technical users who prefer to manage documentation alongside other code.
**Set up Git Sync**
1. Open the section you want to sync from the **Content** part of the sidebar.
2. Click the Git Sync indicator's **Set up** button in the top bar.
3. Follow the instructions to sync the section to your chosen Git repository. Head to the [Git Sync pages](/docs/docs-as-code/git-sync) to find out more.
**Edit your docs from your developer environment**
Once you've synced your section to your Git repository:
1. Open the repository.
2. Create a pull request.
3. Make the changes you want.
{% hint style="info" %}
GitBook supports [Markdown editing](/docs/create-content/formatting/markdown), so you can create and format content using common syntax.
Every standard block in GitBook can be written and formatted using Markdown.
{% endhint %}
**Preview your changes**
You can [preview your changes](/docs/docs-as-code/git-sync/github-pull-request-preview) on your published docs site from the pull request in GitHub or GitLab. Your pull request shows a status with a unique preview URL. Click **Details** on that status to open it and see how your site looks once merged.
**Merge your changes**
Merge your pull request and your content updates both in the GitBook app and on your docs site, if it's live. In the GitBook app, every commit and your merged pull request sync to your section as updates in the version history.
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
#### Customize your docs
**Organize your site navigation**
Add more content to your site — an API reference, a help center, a changelog — at any time, and organize your site's navigation bar so visitors find what they're looking for. Head to [Site structure](/docs/manage-your-site/site-structure) to learn about sections, groups, and variants.
**Customize the look and feel**
Your site looks great out of the box — and under **Customize**, you can set your own [logo, colors, and font](/docs/manage-your-site/customization/icons-colors-and-themes), adjust the layout, and update your [site's visibility](/docs/manage-your-site/site-settings#audience).
{% endstep %}
{% step %}
#### Publish your documentation
You can publish your site with a click at any time.
1. Open your site from your organization **Home**.
2. Click **Publish** in the site header.
Once your site is live, the **Overview** screen updates with a link to the live site.
{% hint style="success" %}
Want to explore publishing in more detail? Check out [our complete guide to creating and publishing content in GitBook](/docs/guides/editing-and-publishing-documentation/complete-guide-to-publishing-docs-gitbook).
{% endhint %}
{% endstep %}
{% endstepper %}
#### Add a custom domain
By default, your site is published with a unique URL in this format:
{% code title="Your site’s default URL" %}
```
https://[organization-name].gitbook.io/[site-title]
```
{% endcode %}
While this may be suitable for some teams, many choose to change their URL to [a custom domain](/docs/publish/custom-domain) or [a custom subdirectory](/docs/publish/custom-domain/setting-a-custom-subdirectory).
1. Expand **Settings** in your site's sidebar.
2. Click **Domain and URL**.
3. Choose the option you want.
4. Follow the instructions to configure the DNS settings with your domain provider.
{% hint style="info" %}
It can take up to 48 hours for your DNS changes to take effect — although they typically propagate much faster.
{% endhint %}
#### Next steps
Cover image
Cover image (dark)
Cover image (dark)
Cover image (dark)
Cover image (dark)
Cover image (dark)
Invite your team to collaborate
Add team members to your organization and set permissions
# LLM-ready docs
Make your published docs easier for AI tools to discover, read, and use
GitBook automatically publishes AI-friendly formats for your docs site.
They help large language models (LLMs), coding agents, and AI search systems. These tools can discover and retrieve accurate documentation without parsing HTML.
## Markdown pages
Append `.md` to any published page URL to view its Markdown. Markdown gives AI tools structured content without the surrounding HTML.
Check out the .md file for this page
## llms.txt
[llms.txt](https://llmstxt.org/) is a proposed standard for LLM-friendly web content. Append `/llms.txt` to your docs site's root URL.
It lists every published page with a Markdown version. AI tools can use this index to discover your documentation.
Check out the /llms.txt for the GitBook docs
## llms-full.txt
Append `/llms-full.txt` to your docs site's root URL. This file includes your full documentation content in one place.
Hidden pages are included in `llms-full.txt`. Hiding a page only removes it from the published table of contents.
Check out the /llms-full.txt file for the GitBook docs
## MCP server for published docs
GitBook exposes a Model Context Protocol (MCP) server for every published docs site. Compatible tools can discover and retrieve your docs as structured resources.
Hidden pages remain available through the site’s MCP server. Hiding a page only removes it from the published table of contents.
Append `/~gitbook/mcp` to your docs site's root URL. For example, GitBook's MCP server is `https://gitbook.com/docs/~gitbook/mcp`.
{% hint style="info" %}
Opening this URL in a browser returns an error. Use a tool that can make HTTP requests.
{% endhint %}
Learn more in [MCP servers for published docs](/docs/ai-for-your-readers/mcp-servers-for-published-docs).
## Optimizing your docs for AI
GitBook handles the delivery layer. Your writing shapes the quality of AI answers.
Write content that AI tools can interpret reliably:
* Give each page a clear purpose.
* Use descriptive headings and short sections.
* State constraints, defaults, and requirements directly.
* Include concrete examples and exact values.
* Update content when your product changes.
These practices improve retrieval, reduce ambiguity, and help people find answers.
### Keeping translations aligned
If you publish in multiple languages, keep each translation aligned with its source.
[Translations](/docs/gitbook-agent/translations) let you localize content with GitBook Agent. When source content changes, GitBook can keep translated versions aligned.
### Measuring AI traffic
Use [Site analytics](/docs/analytics/insights) to track traffic from LLMs and MCP clients.
# Migrate to GitBook
How to import existing content into GitBook from Confluence, Notion, Git and more
You can migrate and unify existing documentation in GitBook using the import tool.
You have the option to import single or multiple pages using our built-in import tool — or [an entire Git repository using Git Sync](#import-using-git-sync).
## Using the Import panel
The Import panel makes it easy to migrate your content into your GitBook organization from another documentation website or from existing files.
When you choose to import from another online documentation site, all you have to do is add the URL of the site and GitBook will handle the rest.
By default, GitBook uses AI to streamline the import process. This will intelligently refine and clean up imported content that doesn’t perfectly match GitBook’s formats — meaning the output will be more polished and use GitBook’s blocks more effectively. You can disable this from the menu.
### Supported import formats
GitBook supports imports from docs websites or files in the following formats:
* Markdown (`.md` or `.markdown`)
* HTML (`.html`)
* Microsoft Word (`.docx`)
GitBook also support imports from:
* Confluence
* Notion
* GitHub Wiki
* Quip
* Dropbox Paper
* Google Docs
If you want to **import multiple pages**, you can upload a ZIP file containing HTML or Markdown files, or use the **Online docs** import option.
{% hint style="info" %}
GitBook is Markdown-based, so importing content in Markdown format will yield the best results. If your current tools support exporting in Markdown, we recommend using that format for a smoother import process.
{% endhint %}
### The Import panel
The import panel in GitBook.
When you create a new section, you’ll have the option to import content in the modal that appears. If you create an empty section, you can also import using the **Quickstart** section at the bottom of the new empty page when you click **Edit**.
Alternatively, you can always import a page or subpage by selecting **Add new** > **Import pages** at the bottom of the [table of contents](/docs/reference/gitbook-ui#table-of-contents), or by opening the **Actions menu** for a page and choosing **Import subpages**.
After choosing an input source, you can select the file you’d like to import.
{% hint style="warning" %}
GitBook imports content from various sources, but differences in product features and document formats may cause variations in the imported content compared to the original source.
{% endhint %}
### Limitations
GitBook currently has the following limits for imported content:
* The maximum number of pages that can be uploaded in a single import is **20**.
* The maximum number of files (images etc.) that can be uploaded in a single import is **20**.
GitBook can't increase these import limits. To import more content at once, use [Git Sync](/docs/docs-as-code/git-sync), which supports up to 5,000 Markdown pages.
***
## Import from a GitHub or GitLab repo using Git Sync
When importing large volumes of content into GitBook, we recommend using [Git Sync](/docs/docs-as-code/git-sync). While our built-in migration tool can handle most imports, Git Sync is better suited for handling larger migrations efficiently.
{% hint style="info" %}
You’ll find the essential steps to import your content below. For more detailed steps and a video demo, head over to our dedicated guide for [importing content into GitBook using Git Sync](/docs/guides/editing-and-publishing-documentation/import-or-migrate-your-content-to-gitbook-with-git-sync).
{% endhint %}
{% stepper %}
{% step %}
**Convert your content into Markdown**
GitBook is Markdown-based, so importing content in Markdown format will yield the best results. If your current tools support exporting in Markdown, we recommend using that format for a smoother import process.
If your content isn’t already in Markdown files, we recommend using a script (like [Markitdown](https://github.com/microsoft/markitdown)) or an online tool to convert your content.
{% endstep %}
{% step %}
**Organize your content in GitHub or GitLab**
When setting up your GitBook site, it’s crucial to organize your content in your GitHub or GitLab repository efficiently. Since Git Sync occurs at the section level, carefully plan how to group your content. Create multiple repositories or folders, ensuring the necessary Markdown files are in the correct locations.
{% endstep %}
{% step %}
**Set up sections and configure Git Sync**
To organize your content, create one or more sections in GitBook as needed. Install the [GitHub Sync](https://www.gitbook.com/integrations/github-sync) or [GitLab Sync](https://www.gitbook.com/integrations/gitlab-sync) integrations in your organization and configure it for those sections. You’ll need to synchronize your section with the folder or repository you set up in the previous step.
{% endstep %}
{% step %}
**Run Git Sync in the direction GitHub → GitBook**
When following the configuration process, make sure you select the direction of GitHub → GitBook. This will result in the contents of your folder or repository being pulled from GitHub or GitLab into GitBook.
{% endstep %}
{% endstepper %}
## Export your content
You can export your GitBook content in two ways:
* **As Markdown**, by syncing with a Git repository. There's no direct Markdown export in the app — sync the section you want to export with an empty GitHub or GitLab repository using [Git Sync](/docs/docs-as-code/git-sync), and the repository becomes your Markdown export. Some blocks don't have a Markdown representation and appear as HTML in the export.
* **As a PDF**, from the page or section's Actions menu. See [PDF export](/docs/publish/pdf-export). You may hit limits when exporting very large sections.
# Site workspace
Learn how the site workspace changes navigation, content structure, and permissions in GitBook
## The sites-first workspace in GitBook
GitBook is now organized around your docs sites. Everything in the app is arranged around the sites you publish, so what you see while editing matches what your visitors see when reading.
This page explains the workspace and what it means for your existing content.
### Why the site workspace
Previously, GitBook organized your work around spaces and collections, and sites were built on top by linking spaces together. That meant the structure you navigated in the app never quite matched the structure of your published site.
The site workspace closes that gap. Your organization contains sites, and every piece of content lives inside a site as a **section**. The hierarchy you edit is the hierarchy your readers get.
### What’s new
#### Home shows all your sites
When you open GitBook, you land on your organization **Home**: your docs sites, recent changes, and organization-wide tools, in one place. To get back to it from anywhere, use the switcher at the top of the sidebar.
#### The sidebar shows your site, not your org
Opening a site replaces the sidebar with that site’s content tree, the same structure visitors see on your published site. Navigate straight to any section and start editing without switching contexts.
The content tree in the sidebar is read-only. To reorganize your site, open the **structure editor**, a dedicated screen that replaces the old Structure tab in Site settings. Changes you make there reflect back in the sidebar immediately.
#### Sections replace spaces
Content in a site now lives in **sections**. If you’ve used GitBook before, a section is what you knew as a space linked to a site. Sections work the same way in the editor. The change is where they live and how they inherit settings from their site.
{% hint style="warning" %}
In the GitBook API, sections are still represented as `space` objects. Nothing changes for API integrations or Git Sync.
{% endhint %}
#### Site tools, one click away
Insights, Analytics, Customization, and Site settings are now items in the site sidebar and open in the main view. You no longer need to dig through nested settings to find them. The screens themselves work exactly as before.
#### Draft sections
New sections start as **drafts**: linked to your site, editable by your team, but not visible to visitors. When you’re ready, publish a draft individually, or publish several at once from the structure editor.
To see how drafts will look on your site, switch the site preview between **Live** and **Live + Drafts**.
#### Organization settings, in context
Organization settings no longer take over the whole screen. They open in context at the organization level, alongside your organization Home, so you can adjust organization-wide options without losing your place.
#### Site-inherited permissions
Sections can inherit permissions from their site instead of from collections. When a member has access through more than one route, the most permissive grant applies. On Enterprise plans, sections shared across sites inherit the broadest access.
This is opt-in per space. Content you don’t opt in keeps the existing collection-based permissions.
### What happens to existing spaces and collections
Nothing is deleted or unpublished.
* Spaces already linked to a site become sections of that site.
* Spaces not linked to any site appear in a new **All content** section, alongside your sites, in the familiar tree view. Collections are preserved there as folders.
* If every space in your organization belongs to a site, the All content section doesn’t appear at all.
# Content structure
Learn how sites, sections, groups, and pages organize your GitBook content.
Content in GitBook is organized around your docs sites. Your organization contains sites, and each site is made up of **sections** — the pages you write and edit live inside a section.
Related sections can be organized into **groups** to shape your site's navigation. The structure you see while editing is the same structure your visitors see on your published site.
:globe:
Sites
Create a site to publish and organize your documentation.
# Sections
A section is a part of your site where you work on a set of related pages. Sections let you write content, organize pages, add integrations, and more. Every section belongs to a site, and you can organize related sections into groups.
{% hint style="info" %}
The GitBook API represents sections as `space` objects. This has no impact on API integrations or Git Sync.
{% endhint %}
### Create a section
1. In your site, click **Add…**.
2. Click **New section**.
Create a section at the top level of your site or inside a group. New sections start as **drafts**: part of your site and editable by your team, but not visible to visitors until you publish them.
Edit a section's name by hovering over the name in the section header.
### Publish a draft section
1. Open the section's **Action menu** .
2. Click **Publish**.
Or publish several drafts at once from the structure editor.
To preview how drafts look on your site, switch the site preview between **Live** and **Live + Drafts**.
### Duplicate a section
1. Open the section's **Action menu** .
2. Click **Duplicate**.
Duplicating a section creates a copy of the source section in the same location (site or group).
{% hint style="warning" %}
Duplicating a section copies the content in the source section. It doesn't copy revisions or version history.
{% endhint %}
### Move or reorder a section
The content tree in the sidebar is read-only. To move a section into or out of a group, or to reorder sections:
1. Open the **structure editor**.
2. Drag the section to its new position.
Changes reflect back in the sidebar — and on your published site — immediately.
### Delete a section
1. Open the section's **Action menu** .
2. Click **Delete**.
{% hint style="warning" %}
**Restore deleted sections from the Trash for up to 7 days.** After that, GitBook deletes them permanently.
{% endhint %}
# Groups
Organize related sections within your site
Section groups let you organize related sections within your site, making your site's structure easier for visitors to navigate.
Section groups are different from [Pages](/docs/create-content/content-structure/page). Page groups organize pages within one section. Section groups organize sections in site navigation. Both are called groups, but you configure their icons independently.
### Create a group
1. In your site, click **Add…**.
2. Click **New group**.
3. Choose a title and an icon that represents the group.
New groups start as **drafts**: they aren't visible on your published site until you publish them.
### Add sections to a group
1. Open the **structure editor**.
2. Drag the section into or out of the group.
Or create a new section directly inside a group.
### Publish a group
1. Open the group's **Action menu** .
2. Click **Publish**.
Or publish several drafts at once from the structure editor.
To preview how draft groups look on your site, switch the site preview between **Live** and **Live + Drafts**.
### Rename a group
1. Click the **Action menu** icon next to the group.
2. Click **Rename**.
3. Change the group's title or icon.
### Delete a group
1. Open the group's **Action menu** .
2. Click **Delete**.
# Pages
Add pages, page groups or external links — and learn about the options you have on each page
A page is the place where you can add, edit and embed content. Pages always live inside a section, allowing you to group related content for the topics or areas you're covering.
When you publish your site, each section appears in your site's navigation, and the pages inside it all appear under that section.
### Table of contents
Create as many pages as you need in a section. They're all visible on the left sidebar of your screen in your section's table of contents. The table of contents appears in the same place on your published site, unless [you choose to hide it](#page-options).
{% hint style="info" %}
**Section landing page**
The first page in your table of contents is always your section's landing page, even if it's hidden from the table of contents.
{% endhint %}
### Create a new page
1. Enter live edit mode or open a change request.
2. Click **Add new\...** at the bottom of your table of contents.
3. Click **Page**.
Or hover between pages in the table of contents and click the **+** icon that appears.
An empty page in GitBook. You can see it listed in the table of contents on the left-hand side.
### New page option missing
{% hint style="warning" %}
If live edits are disabled for your section, create or edit a change request. In a change request, the **New page** button — which creates pages, page groups, and links — is available in the table of contents.
You might also lack the permissions to edit a page.
{% endhint %}
### Organizing your content
There are three ways to organize your content in the table of contents:
#### Pages
A page has a title, an optional description, and an area where you can write and add any kind of content.
Nest pages by dragging and dropping a page below another in the table of contents. Doing this creates a **subpage**.
If you add subpages to an empty parent page, GitBook automatically generates a 'contents' page with links to all the subpages in the published version of your docs.
{% hint style="info" %}
**Tip:** There's no limit to page nesting, but avoid more than three levels to keep your navigation simple.
{% endhint %}
When you change the title of a page, the page's slug (the part at the very end of the URL, such as `/hello-world`) also changes — unless you've manually set the page's slug previously.
A published page URL follows the navigation tree, not your Git Sync file layout. It includes the top-level section or group slug, every ancestor page or group slug, and the page's own slug.
For example, this Git Sync file layout:
```
content/
└── setup/
└── install.md
```
Can have this navigation tree:
```
API
└── Guides
└── Install
```
If the slugs are `api`, `guides`, and `install`, the published URL is `/api/guides/install`. The file path doesn't determine the URL.
To change the title, link title, or slug of a page:
1. Open the page's **Action menu** .
2. Click **Edit title & slug**.
#### Page link title
To give your page a longer SEO-friendly title while keeping a shorter title for your navigation entry and links, define a link title.
1. Open the page's **Action menu** .
2. Click **Edit title & slug**.
3. In the **Edit page** dialog, enable and define a link title for that page.
If you're using Git Sync, set the page link title in `SUMMARY.md` on the page link:
```markdown
# Table of contents
* [Page main title](page.md "Page link title")
```
{% hint style="info" %}
**Note:** Page link titles appear in the table of contents, the pagination buttons at the bottom of each page, and any relative links you add to that page.
{% endhint %}
Page link titles are optional — if you don't add one, the page uses its standard title.
#### Page groups
Page groups bring related pages together within a section's table of contents. You can add an icon to each page group.
{% hint style="info" %}
Page groups organize pages within one section. Section groups organize sections in site navigation. They are different objects, even though both are called groups. See [Groups](/docs/create-content/content-structure/collection).
{% endhint %}
Create a page group by clicking **Add new\...** > **Group** at the bottom of your table of contents.
Page groups live only at the **top level** of the table of contents — you can't nest page groups inside each other.
{% hint style="warning" %}
Page-group slugs become part of every child page URL. Adding, renaming, or removing a page group changes child page URLs and breaks existing links unless you add redirects. See [Site redirects](/docs/publish/site-redirects).
{% endhint %}
To change the title, slug, or icon of a page group:
1. Click the **Action menu** icon next to the group title in the table of contents.
2. Click **Rename**.
3. Update the title, slug, or icon.
{% hint style="warning" %}
`SUMMARY.md` doesn't store page-group icons. GitBook stores them, and Git Sync doesn't round-trip them. If your repository recreates a page group, GitBook doesn't restore the original icon automatically. Set the icon again in GitBook.
{% endhint %}
#### External links
Add links to your table of contents to take people directly to the linked content.
Create an external link by clicking **Add new\...** > **External link** at the bottom of your table of contents.
### Page icons and emojis
To improve visibility for readers when skimming your table of contents, add an optional icon or emoji to individual pages. The icon or emoji appears in the table of contents, and next to the title at the top of the page.
To add an icon or emoji, click the **Add icon** button when hovering the page title, or the emoji button to the left of the title.
### Page options
In the **Page options** menu, customize the look and feel of a selected page within a section and control its visibility.
#### Layout
Open the **Page options** menu or change a page's cover by hovering over the page title. The buttons appear just above the page title.
In the **Page options** side panel, choose how each page displays to visitors of your **published** content. There are three layout presets to choose from, or you can create a custom layout.
Each layout preset toggles the following parts of the page on or off:
* Page title
* Page description
* Table of contents
* Page outline
* Next/previous links
* Page metadata
* Tags
Tag a page with one or more tags from **Library** → **Tags**. Turn on **Show tags on page** to display them in the page header. Or pick one tag as the page's primary tag, which GitBook can show next to the page in the table of contents. Learn more in Tags.
Set your page's global width from this menu, too. Choosing **Wide** gives blocks such as tables, cards, and code blocks more space on the published page. Use this for eye-catching landing pages.
#### Visibility
Choose which pages to show or hide in your published documentation, and whether each page appears in your site's search and in search engines.
To hide a page or group of pages from your site's table of contents:
1. Open the page's **Action menu** .
2. Toggle **Hide page**.
Hidden pages are only hidden from the published table of contents. They remain available through the site's MCP server and in `llms-full.txt`.
If you're using Git Sync, hidden pages include the following front matter in the Markdown file:
---
hidden: true
---
{% hint style="warning" %}
Hiding **Page title** or **Page description** only hides the page header in published content. It doesn't remove headings inside the page body. Learn more about heading levels in Headings.
{% endhint %}
#### Metadata (SEO)
Use **Page options → Metadata** to control how search engines understand relationships between similar pages (for example: documentation versions or content variants).
* **Canonical URL**: the preferred (authoritative) URL for this page. Search engines treat it as the 'source of truth'. Use it when multiple URLs show the same content.
* **Alternate URLs**: other URLs for the same content in another variant. For example, another version or language. They help search engines group variants instead of treating them as duplicates.
Both fields support selecting another GitBook page (recommended) or entering an external URL.
{% hint style="info" %}
A common pattern for versioned docs is to set older pages to be canonical to the latest equivalent page (for example, `1.0` → `2.0`), and then list older versions as alternates on the latest page.
{% endhint %}
#### Moving pages between sections
GitBook doesn't currently support moving individual pages between sections in the app. To move a page's content to another section:
* **Copy and paste** — select the page's content with the `Esc` key, then copy and paste it into the destination. Some blocks may need reconfiguring; comments and page history aren't copied, and images need re-uploading in the new section.
* **Use Git Sync** — if both sections sync with repositories, copy the files between repositories and add the page titles to the destination's `SUMMARY.md`. See [Git Sync](/docs/docs-as-code/git-sync).
### Page covers
Set a page cover for each page of your documentation. When you click the **Page cover** option, GitBook adds a default cover immediately. The ideal cover image size is 1990 × 480 pixels — covers are locked to this aspect ratio, so the proportions are maintained across screen sizes. From here, you can:
* **Change the cover image**
1. Hover over the page cover and click **Change cover**.
2. Choose or upload an image. The ideal size is 1990x480 pixels.
* **Reposition the cover image**
1. Hover over the page cover and open the **Action menu** .
2. Click **Reposition**.
3. Drag the image into place and click **Save**.
* **Remove the cover image**
1. Hover over the page cover and open the **Action menu** .
2. Click **Remove**.
* **Full width and hero width**
Change the style of your page cover to span the full width of your screen or just the width of your content.
1. Hover over the page cover and open the **Action menu** .
2. Click your preferred option.
# Tags
Tags are reusable labels you can add to pages and update blocks — this page tells you how to create, add and manage tags
Use tags to group related content, convey release states, mark outdated content, or anything else that helps readers scan your documentation.
#### Tag a page
Open the page, then open the **Tags** menu — accessible by hovering over the page title — and create or add tags. You can drag tags around to change the order in which they appear on the page.
1. Open the page.
2. Hover over the page title and open **Page options**.
3. Add one or more tags.
Drag tags to change the order in which they appear on the page.
#### Show or hide tags on a page
Tags display at the top of the page by default. To hide a page's tags while keeping the associated metadata:
* Open the **Tags** menu
* Turn off **Show tags on page** to keep tags as metadata only
1. Open **Page options**.
2. Turn off **Show tags on page**.
#### Display a tag in the table of contents
For each page, you can pick one tag to display in the table of contents. To choose which tag displays:
* Open the **Tags** menu
* Use the **Display in table of contents** dropdown to choose your tag
* You can also click into a tag and **Display**, **Remove** or **Replace in table of contents**.
1. Open **Page options**.
2. Under **Tags**, choose your tag from the **Display in table of contents** dropdown.
#### Tag an update block
Each update block can have its own tags.
1. Open the update block.
2. Click **Add tag** below the date.
3. Use the tag picker to add, remove, or reorder tags.
#### Manage tags in the Library
To view, create and manage tags for your space, open the **Library** from the [table of contents](/docs/create-content/content-structure/page#table-of-contents) and choose **Tags**. You can quickly access this by opening the **Tags** menu and selecting **Open Tag Library**.\
\
You can also view an individual tag in the library by selecting the tag and choosing **Show in Library**.
To view, create, and manage tags for your section:
1. Open the **Library** from the table of contents.
2. Click **Tags**.
Each tag has:
* A label — what readers see
* A slug — a stable identifier
* An optional icon or emoji
#### Tags in Markdown
If you use Git Sync, tags appear in the page frontmatter:
```yaml
---
description: "Tags are reusable labels you can add to pages and update blocks — this page tells you how to create, add, and manage tags"
tags:
- news
- experiment
- tag: beta
primary: true
- pro
---
```
Use a string for a standard tag. Use `primary: true` on one tag to make it the page's primary tag — GitBook can show that tag in the table of contents.
# All content
Browse, search, and manage content across all of your sites, and content that isn’t part of a site yet, from one screen
In GitBook, your content lives in [sections](/docs/manage-your-site/site-structure/site-sections) that belong to a docs site. The **All content** screen gives you one place to see everything in your organization: content from every site, and content that isn’t part of a site yet.
### Open All content
From your organization **Home**, click **Content** in the sidebar.
### Browse, filter, and search
Each row shows the content’s name and when it was last updated. Click a row to open it.
To narrow the list, click the **All sites** filter and choose a site. To find something by name, use the **Search content** field.
### Create content
Click **Create content** to start new content from this screen.
It’s best that content belongs to a parent site. Create new content inside a site whenever you can — it keeps your structure, permissions, and publishing in one place. See [Site structure](/docs/manage-your-site/site-structure) to learn how sections fit into a site.
### Content that isn’t part of a site
If your organization used GitBook before our navigation remodel, some of your content may not belong to a site. It still appears in **All content**, and you can keep editing and collaborating on it here.
To publish that content, add it to a site as a section. Learn more in [Site structure](/docs/manage-your-site/site-structure).
# Format content
Format your content in various ways using the context menu or keyboard shortcuts
To format your text, simply select the words you want and choose one of the formats from the context menu — or format your text using a keyboard shortcut or through Markdown syntax.
{% hint style="info" %}
We've written these shortcuts using Mac keys. Use **Control** in place of **⌘ (Command)** on Windows or Linux operating systems. Check out our keyboard shortcuts section to see all the shortcuts for all operating systems.
{% endhint %}
#### Bold
Keyboard shortcut: ⌘ + B
{% tabs %}
{% tab title="Markdown" %}
```markdown
**Bold**
```
{% endtab %}
{% endtabs %}
#### Italic
Keyboard shortcut : ⌘ + I
{% tabs %}
{% tab title="Markdown" %}
```markdown
_Italic_
```
{% endtab %}
{% endtabs %}
#### Strikethrough
Keyboard shortcut: ⇧ + ⌘ + S
{% tabs %}
{% tab title="Markdown" %}
```markdown
~~Strikethrough~~
```
{% endtab %}
{% endtabs %}
#### Code
Keyboard shortcut: ⌘ + E
{% tabs %}
{% tab title="Markdown" %}
```markdown
`Code`
```
{% endtab %}
{% endtabs %}
#### Link
Keyboard shortcut: ⌘ + K
When you add a link to text on your page, you'll be prompted to provide the link. You can add any URL, but if you're linking to another page or section in your site, we recommend using a relative link.
This is a [link to an external page](https://www.gitbook.com).
This is a [link to another page in this section](/docs/create-content/blocks).
This is a [link to a section on this page](#code).
This is a [link that starts an email to a specific address](mailto:support@gitbook.com).
#### Color and background color
Click the color icon in the context menu, and choose a color for the text or its background.
This text is orange.
This text background is orange.
### Right-to-left text
GitBook doesn't currently support right-to-left contributions. Paragraphs and headings automatically detect RTL text and adapt their layout, but lists and other content blocks may not align properly, and font quality can be reduced for some languages.
# Inline content
Use the inline palette to add images, links, math & TeX, and more
Add inline elements to your content.
The inline palette lets you quickly add extra content to your text block without moving your hands away from the keyboard. Simply hit `/` on any text block to open the inline palette. The forward slash will be replaced by the content you choose to insert.
## Annotations
With annotations, you can add extra context to your words without breaking the reader’s train of thought. You can use them to explain the meaning of a word, insert extra information, and more. Readers can hover over the annotated text to show the annotation above the text.
### Create an annotation
To create an annotation, select the text you would like to annotate and click the **Annotate** option in the context menu. Once you’ve written your annotation, click outside of it to continue writing in the text block.
### Markdown representation
You can write content as [Markdown footnotes](https://www.markdownguide.org/extended-syntax/#footnotes) to add them as annotations in GitBook. Footnote indicators should appear immediately after the word you wish to annotate; they should not appear after punctuation marks or other symbols.
```markdown
Here's a simple footnote[^1], and here's a longer one[^bignote].
[^1]: This is the first footnote.
[^bignote]: Here's one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
`{ my code }`
Add as many paragraphs as you like.
```
### Rendered example
The Markdown source creates an annotation on the referenced text:
```markdown
Annotations add extra context[^annotation-example].
[^annotation-example]: Hover over “extra context” to read this annotation.
```
It renders as follows. Hover over the annotated text to preview the annotation:
[Annotations add extra context.](#user-content-fn-1)[^1]
## Images
Inline images will sit alongside your text on the page.
By default, images are set to their original size with a maximum width of 300px. You can change the size by clicking the image to open the formatting palette, then choosing one of the three options:
1. **Inline size:** The image is proportionally sized to the font — great for icons and badges.
2. **Original size:** The image will remain inline at its original size, with a maximum width of 300 pixels.
3. **Convert to block:** This turns an inline image into a image block, which is as wide as your content.
{% hint style="info" %}
Image blocks offer more options, including more sizes and the ability to add a caption — but will not appear inline with your text.
{% endhint %}
### Representation in Markdown
{% code overflow="wrap" %}
```markdown
Here is an inline image:
```
{% endcode %}
It renders as follows: Here is an inline image:
## Emojis
You can add emojis by hitting `/` to open the inline palette. Alternatively, type `:` and a list of emojis will pop up directly in line — you can start typing the name of an emoji to narrow down the selection.
### Representation in Markdown
{% code overflow="wrap" %}
```markdown
:house:
:smile:
:dog:
```
{% endcode %}
They render as follows: :house: :smile: :dog:
## Links
You can insert three different types of links:
* [Relative links](#relative-links)
* [Absolute links](#absolute-links)
* [Email address `mailto` links](#email-address-mailto-links)
### Relative links
Relative links are links created by linking to pages that already exist in your section. The advantage of using relative links is that if the page's URL, name, or location changes, its reference will be kept up to date — so you'll end up with fewer broken links.
Here’s how to insert a relative link:
1. Click somewhere in your paragraph where you want to insert the link, or select some text.
2. Hit / to open the inline palette and choose Link, click the **Link** button in the context menu, or hit **⌘ + K**.
3. Start typing the title of the page you want to link to.
4. Select the page from the drop-down search results.
5. Hit `Enter`.
### Absolute links
Absolute links are external links that you can copy and paste into your content. They're great when you want to link to something outside your documentation.
To insert an absolute link:
1. Click somewhere in your paragraph where you want to insert the link, or select some text.
2. Hit / to open the inline palette and choose Link, click the **Link** button in the context menu, or hit **⌘ + K**.
3. Paste the URL you want to link to.
4. Hit `Enter`.
{% hint style="info" %}
**Why don't external links open in a new tab?**
When you add a link to an external site in your docs, it will open in the same tab.
GitBook follows this [W3C-recommended behavior](https://www.w3.org/TR/WCAG20-TECHS/G200.html) to support [accessibility](https://it.wisc.edu/learn/make-it-accessible/websites-and-web-applications/when-to-open-links-in-a-new-tab/) and ensure a consistent, inclusive experience for your readers.
{% endhint %}
### Email address mailto links
Email address `mailto` links are useful when you want your visitors to click on a link that will open up their default email client and fill in the `To` field with the email address of your link, so they can write an email to send.
Here’s how to insert an email address `mailto` link:
1. Click somewhere in your paragraph where you want to insert the link, or select some text.
2. Hit / to open the inline palette and choose Link, click the **Link** button in the context menu, or hit **⌘ + K**.
3. Paste or type `mailto:something@address.com`, replacing `something@address.com` with the email address you would like to use.
4. Hit `Enter`.
### Representation in Markdown
```markdown
[This is a relative link to another page in this section](../content-structure/page.md)
[This is an absolute link](https://www.gitbook.com/blog)
[This is a link](mailto:support@gitbook.com) to our support email address
```
They render as follows:
[This is a relative link to another page in this section](/docs/create-content/content-structure)\
[This is an absolute link](https://www.gitbook.com/blog)\
[This is a link](mailto:support@gitbook.com) to our support email address
## Math & TeX
Using this option, you can create inline math formulas in your content. We use the [KaTeX](https://katex.org/docs/supported.html) library to render formulas.
{% hint style="info" %}
You can also insert a block-level math formula by opening the command palette in an empty block and choosing the second Math & TeX option.
{% endhint %}
### Representation in Markdown
```markdown
This is an inline formula: $$f(x) = x * e^{2 pi i \xi x}$$
```
It renders as follows: This is an inline formula: $$f(x) = x \* e^{2 pi i \xi x}$$
## Buttons
Buttons are a great way to highlight calls to action or add a search or Ask AI bar to your docs. You can use them to send readers somewhere, or help them find answers.
### Button actions
Buttons can do more than link to a URL. You can also turn a button into a search or ask GitBook Assistant bar — right from the page. These actions work on published pages, too — as you can see from the examples below.
You can configure the following actions:
#### **Add a link button**
Send readers to another page or an external URL:Learn more about Assistant
#### **Add a search bar**
Open search with an optional preset query:
#### **Add a Ask AI/GitBook Assistant bar**
Open GitBook Assistant with an optional preset prompt:
#### **Add a disabled button**
Show a button that’s intentionally inactive:Inactive button
### Create and configure a button
1. Type `/` and choose **Button**.
2. Click the button to open the **Label** menu.
3. Choose an action, then set the label and style.
4. Optional: add a preset search query or Assistant prompt.
### Styles
Link and inactive buttons have both primary and secondary styles. Here are a couple of examples:
Sign up to GitBookGo to top
### Representation in Markdown
```markdown
GitBook
```
It renders as follows: GitBook
## Icons
Icons add visual context to paragraphs, cards, and other content. They use the visual style defined in your customization settings.
Use an `` element with both forms of the icon name. The Font Awesome class and token must match:
```markdown
:rocket:
```
Choose an icon name from the [Font Awesome icon picker](https://fontawesome.com/search). Unsupported names might not render or survive Git Sync.
:facebook::github::x-twitter::instagram:
### Representation in Markdown
```markdown
:github:
```
It renders as follows: :github:
## Expressions
Expressions allow you to dynamically display content defined in a variable. Expressions can be inserted from the `/` menu. Once inserted, clicking on the expression will bring up the expression editor, allowing you to reference and [conditionally format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator) your variable.
### Representation in Markdown
```markdown
Welcome to page.vars.inlineExampleProduct.
```
It renders as follows: Welcome to page.vars.inlineExampleProduct.
[^1]: This is an annotation.
# Markdown
Write Markdown directly in the editor to easily create content using common syntax
Write Markdown in GitBook.
GitBook’s editor allows you to create formatted content using Markdown.
Markdown is a popular markup syntax that’s widely known for its simplicity. GitBook supports it as a keyboard-friendly way to write rich and structured text.
{% hint style="info" %}
You can learn more about Markdown itself by visiting [Common Mark](https://commonmark.org/help/).
{% endhint %}
### Text formatting
GitBook supports all the classic inline Markdown formatting:
| Formatting | Markdown version | Result |
| ------------- | ----------------- | ----------------- |
| Bold | `**bold**` | **bold** |
| Italic | `_italic_` | *italic* |
| Strikethrough | `~strikethrough~` | ~~strikethrough~~ |
| Inline code | `` `code` `` | `code` |
### Line breaks
Press `Enter` to start a new paragraph.
Press `Shift` + `Enter` to insert a soft line break in the same paragraph.
### Pasting Markdown
When pasting Markdown content directly into the editor, it’s important to use the **Paste and Match Style** option (typically Shift + Cmd + V on Mac or Shift + Ctrl + V on Windows).
If you use the standard Paste option for content copied from another editor or from the web, it may be inserted as a code block instead of formatted text.
### Titles
* Heading 1: `# A first-level title`
* Heading 2: `## A second-level title`
* Heading 3: `### A third-level title`
### Code blocks
` ```⏎ ` creates a new code block.
` ```py⏎ ` creates a new code block with Python syntax highlighting.
We use [Prism](https://github.com/PrismJS/prism) for syntax highlighting. Use [Test Drive Prism](https://prismjs.com/test.html#language=markup) to check supported languages.
If GitBook and Prism differ, we might be a version or two behind.
### Lists
GitBook automatically detects and creates ordered and unordered lists as you type.
* Begin a line with `-` or `*` to start an unordered bullet list.
* Begin a line with `1.` to start a numbered list.
* Begin a line with `- [ ]` to start a task list.
When writing lists, hit `Tab` to indent, and `Shift+Tab` to outdent.
### Quotes
Begin a line with `>` to create a block quote. If you select an entire paragraph from start to end, typing `>` will wrap the content in a block quote.
> This is a block quote.
### Dividers
Type `---` then hit `Enter` to create a divider on your page.
***
This is an example of a divider.
# Blocks
Add and edit blocks within your content
GitBook is a block-based editor, meaning you can add different kinds of blocks to your content — from standard text and images to interactive blocks. Your pages can include any combination of blocks you want, and there’s no limit to the number of blocks you can have on a page.
GitBook's built in content blocks.
### Inserting a new content block
You can insert a new content block below an existing block using your mouse:
1. Hover over the block above the place you need the new content block.
2. Click on the `+` icon that appears on the left to open the insert palette.
3. Select the block you want from the drop-down menu to insert it.
Alternatively, on a new line, you can press `/` to launch the insert palette, which lists all the available blocks. You can scroll through the list to find the one you want, or use your keyboard to search for the block you want, navigate up and down the list, and insert it with `Enter`.
### Exiting a block
Some content blocks capture the editing cursor to allow you to add content in the context of that block. For example, when you’re writing in [a hint block](/docs/create-content/blocks/hint), hitting `Enter` will add a new line within the hint block, rather than a new paragraph below.
When you are done, you can continue adding new content to the page either by inserting a new block using the `+` button to the left of your content, or by hitting **⌘ + Enter** on a Mac or **Ctrl + Enter** on a PC.
### Selecting blocks and interacting with selected blocks
You can select a single block by pressing the `Esc` key with the cursor in the block. You can also select multiple blocks by highlighting content within them and hitting `Esc`.
Once selected, you can:
* Select more blocks by clicking on them while keeping the **Shift ⇧** key pressed.
* Moving up and down to select the block above or below, using the **↑** and **↓** keys
* Copy the entire block using **⌘ + C** (Mac) or **Ctrl + C** (Windows)
* Cut the entire block using **⌘ + X** (Mac) or **Ctrl + X** (Windows)
* Delete the selected block or blocks using **⌫** or **Del**.
# Paragraphs
Add a paragraph block to insert formatted text, inline images and more
A paragraph is the most basic content block you can use on GitBook.
{% hint style="info" %}
You can [add other inline content](/docs/create-content/formatting/inline) to your paragraph, such as emojis, images and Math & TeX.
You can also [format your text](/docs/create-content/formatting) using the context menu or keyboard shortcuts, or using [Markdown](/docs/create-content/formatting/markdown).
{% endhint %}
### Example of a paragraph
Professionally printed material in English typically does not indent the first paragraph, but indents those that follow. For example, Robert Bringhurst states that we should “set opening paragraphs flush left.”
### Representation in Markdown
Because a paragraph block is just text, that’s how it’s represented in Markdown.
{% code overflow="wrap" %}
```markdown
Professionally printed material in English typically does not indent the first paragraph, but indents those that follow. For example, Robert Bringhurst states that we should “set opening paragraphs flush left.”
```
{% endcode %}
# Headings
Add heading blocks to a page to organize your content and improve SEO
Headings help give your documents structure — and using keywords in headings will also help search engines understand that structure, which can help your page rank higher in search results.
GitBook offers three levels of headings. Heading levels 1 (H1) and 2 (H2) will appear in the [page outline](/docs/reference/gitbook-ui#page-outline).
### Anchor links
When you add a heading to a page, it creates an anchor link. You can then link directly to these specific sections, to point people to relevant information.
#### Link to an anchor
You can see anchor links in public content, or private content in read-only mode, by hovering over the title and clicking the `#` that appears next to it. This will update the URL in your browser’s top bar, so you can copy it to use elsewhere.
If you want to link to a particular anchor from a page within your section, you can use a [relative link](/docs/create-content/formatting/inline#relative-links), which will update if you change the heading to prevent the link from breaking.
#### Edit an anchor
By default, the anchor link will be identical to the text in your header. If you plan to link to that URL outside of GitBook, changing the header in future will break the anchor link. The link will then take visitors to the top of the page, rather than the anchor location.
To avoid this, you can manually set the anchor link by opening the **Options menu** for the header, then choosing **Edit anchor**. You can then enter the anchor link you wish to use — this will remain the anchor even if you change the header itself.
### Representation in Markdown
GitBook generates SEO optimized pages, meaning page titles in GitBook are automatically represented in markdown as a first level heading:
```markdown
# I'm a page title
```
This means that if you [sync your content with Git](/docs/docs-as-code/git-sync), page headers added through the editor will be represented as one level lower:
{% code overflow="wrap" %}
```markdown
## My heading 1
### My heading 2
#### My heading 3
```
{% endcode %}
### Heading examples
## My heading 1
### My heading 2
#### My heading 3
{% hint style="info" %}
Page titles are separate from heading blocks in the page body. If you hide the page title in **Page options**, your H1, H2, and H3 headings still appear.
{% endhint %}
# Unordered lists
Add an unordered list block to create bullet point lists
Unordered lists are great for making a series of points that do not necessarily need to be made in a particular order. They are effectively bullet point lists, with support for nesting as needed.
When typing a list in GitBook, you can exit the list and start a new empty block below by hitting `Enter` twice.
### Example of unordered list
* Item
* Nested item
* Another nested item
* Yet another nested item
* Another item
* Yet another item
{% hint style="info" %}
To create nested items, you can use **Tab** to indent and **⇧ + Tab** to outdent.
{% endhint %}
### Representation in Markdown
```markdown
- Item
- Nested item
- Another nested item
- Yet another nested item
- Another item
- Yet another item
```
# Ordered lists
Add an ordered or numbered list to a page
Ordered lists, also called numbered lists, help you prioritize items or create a list of steps.
### Example of ordered list
1. Item 1
1. Nested item 1.1
1. Nested item 1.1.1
2. Nested item 1.2
2. Item 2
3. Item 3
{% hint style="info" %}
To create nested items, you can use **Tab** to indent and **⇧ + Tab** to outdent.
{% endhint %}
### Representation in Markdown
```markdown
1. Item 1
1. Nested item 1.1
1. Nested item 1.1.1
2. Nested item 1.2
2. Item 2
3. Item 3
```
### Adding an inline image to an ordered list
Adding images inside of ordered lists is possible in GitBook
If you want to add an image within an ordered list, add it using the insert menu, then on the row below the image type `3.` then hit `Space`, and the ordered list will continue.
1. Item 1
2. Item 2
3. Item 3
4. Item 4
# Task lists
Add a task list to display tasks that can be completed
Task lists allow you to create a list of items with checkboxes that you can check or uncheck.
{% hint style="info" %}
**Note:** Readers of your published site can't check or uncheck these boxes. You can decide which boxes are checked and unchecked when you create the content.
{% endhint %}
### Example of a task list
* [ ] Here’s a task that hasn’t been done
* [ ] Here’s a subtask that has been done, indented using `Tab`.
* [ ] Here’s a subtask that hasn’t been done.
* [ ] Finally, an item, unindented using `shift` + `tab`.
### Representation in markdown
```markdown
- [ ] Here’s a task that hasn’t been done
- [x] Here’s a subtask that has been done, indented using `tab`
- [ ] Here’s a subtask that hasn’t been done.
- [ ] Finally, an item, unindented using `shift` + `tab`.
```
# Hints
Add a hint to a page to draw your reader’s attention to specific pieces of important information.
Hints, or callouts, are a great way to bring the reader’s attention to specific elements in your documentation, such as tips, warnings, and other important information.
There are four different hint styles — you can change the style by opening the block’s **Options menu** and selecting the style you want. Each style uses a default icon, but you can customize the icon by clicking on it and choosing another one from [our icons set](/docs/create-content/formatting/inline#icons).
Hint blocks support [inline content](/docs/create-content/formatting/inline) and [formatting](/docs/create-content/formatting), as well some specific block types. To see which block types you can use in a hint, hit `/` on an empty line and check the [insert palette](/docs/create-content/blocks#inserting-a-new-content-block).
### Examples of hint blocks
{% hint style="info" %}
**Info hints** are great for showing general information, or providing tips and tricks.
{% endhint %}
{% hint style="success" %}
**Success hints** are good for showing positive actions or achievements.
{% endhint %}
{% hint style="warning" %}
**Warning hints** are good for showing important information or non-critical warnings.
{% endhint %}
{% hint style="danger" %}
**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
{% endhint %}
{% hint style="info" icon="books" %}
This hint block has a custom icon.
{% endhint %}
{% hint style="info" %}
#### **This is a H2 heading**
This is a line
This is an inline image
* This is a second line using an unordered list and color
{% endhint %}
To add a heading to your hint, you need to create a heading block as the the first block in the hint.
### Representation in Markdown
```markdown
{% hint style="info" %}
**Info hints** are great for showing general information, or providing tips and tricks.
{% endhint %}
{% hint style="success" %}
**Success hints** are good for showing positive actions or achievements.
{% endhint %}
{% hint style="warning" %}
**Warning hints** are good for showing important information or non-critical warnings.
{% endhint %}
{% hint style="danger" %}
**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
{% endhint %}
{% hint style="info" icon="books" %}
This hint block has a custom icon.
{% endhint %}
{% hint style="info" %}
## This is a H2 heading
This is a line
This is an inline image
- This is a second line using an unordered list and color
{% endhint %}
```
# Quotes
Add a quote block to a page to highlight copy you’re adding from elsewhere, or to draw attention to a specific part of your text
Quotes are useful when you want to include something from another source.
Start a quote by typing `>` followed by pressing `Space` in an empty paragraph, or use the[ insert palette](/docs/create-content/blocks#inserting-a-new-content-block). You can also convert a paragraph block to a quote by highlighting the entire paragraph and hitting `>`.
### Example of a quote
> "No human ever steps in the same river twice, for it’s not the same river and they are not the same human." — *Heraclitus*
### Representation in Markdown
{% code overflow="wrap" %}
```markdown
> "No human ever steps in the same river twice, for it’s not the same river and they are not the same human." — _Heraclitus_
```
{% endcode %}
# Code blocks
Add a code block to a page to include sample code, configurations, code snippets and more
You can add code to your GitBook pages using code blocks.
When you add a code block, you can choose to [set the syntax](#set-syntax...), [show line numbers](#with-line-numbers), [show a caption](#with-caption), and [wrap the lines](#wrap-code). It’s also easy to [copy the contents of a code block to the clipboard](#copying-the-code), so you can use it elsewhere
A code block may be useful for:
* Sharing configurations
* Adding code snippets
* Sharing code files
* Showing usage examples of command line utilities
* Showing how to call API endpoints
* And much more!
### Add a code block
1. To add a code block, place your cursor on an empty line and type `/`.
2. In the quick insert menu, select **Code block**.
3. GitBook inserts the block and places your cursor inside it, ready for you to paste or type code.
### Example of a code block
{% code title="index.js" overflow="wrap" lineNumbers="true" %}
```javascript
import * as React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(, window.document.getElementById('root'));
```
{% endcode %}
You can also combine code blocks with a [tabs block](/docs/create-content/blocks/tabs) to offer the same code example in multiple different languages:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
let greeting = function (name) {
console.log(`Hello, ${name}!`);
};
greeting("Anna");
```
{% endtab %}
{% tab title="Ruby" %}
```ruby
greeting = lambda {|name| puts "Hello, #{name}!"}
greeting.("Anna")
```
{% endtab %}
{% tab title="Elixir" %}
```elixir
greeting = fn name -> IO.puts("Hello, #{name}!") end
greeting.("Anna")
```
{% endtab %}
{% endtabs %}
### Code block options
When you click on the **Options menu** next to the code block, or the **Actions menu** in the block itself, you’ll see a number of options you can set.
#### Set syntax…
You can set the syntax in your code block to any of the supported languages. This will enable syntax highlighting in that language, too.
{% hint style="info" %}
We use [Prism](https://github.com/PrismJS/prism) for syntax highlighting. You can use [Test Drive Prism](https://prismjs.com/test.html#language=markup) to check which languages Prism supports. If you notice a mismatch between GitBook and Prism, there’s a chance we’re a version or two behind. We’ll catch up soon!
{% endhint %}
{% code title="filename.txt" %}
```
// Some code
```
{% endcode %}
#### With line numbers
This will toggle line numbers for your code on and off.
Showing line numbers is useful when the code represents the contents of a file as a whole, or when you have long code blocks with lots of lines. Hiding line numbers is useful for snippets, usage instructions for command line or terminal expressions and similar scenarios.
#### With caption
This will toggle a caption that sits at the top of the block, above your lines of code.
The caption is often the name of a file as shown in [our example above](#example-of-a-code-block), but you can also use it as a title, description, or anything else you’d like.
#### Wrap code
This will toggle code wrapping on and off, so long lines of code will wrap to all be visible on the page at once.
Wrapping lines is useful when your code is long and you want to avoid having the viewer scroll back and forth to read it. If you toggle **Wrap code** on, you may also want to show line numbers — this will make it easier to read the code and understand where new lines start.
#### Expandable
This will toggle showing the code in full (when the toggle is off) or a collapsed window of the code which the user can expand (when the toggle is on).
The collapsed view defaults to showing 10 lines of code with an button to expand to show the full code block. If there are less than 10 lines of code, all the content will be shown.
### Code block actions
As well as the options above, you can also change the language the code block displays, and copy your code instantly.
#### Copy the code
Hover over a code block and a number of icons will appear. Click the middle icon to copy the contents of the code block to your clipboard.
### Representation in Markdown
````markdown
{% code title="index.js" overflow="wrap" lineNumbers="true" %}
```javascript
import * as React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(, window.document.getElementById('root'));
```
{% endcode %}
````
# Files
Manage and add files to your site such as PDFs, videos, documents and more
You can upload files to your GitBook section and add them to your page for people to view or download.
You can show some files, such as images and OpenAPI files, on the page itself for people to see without clicking anything. For others, such as PDFs, users will have to click to view or download it.
You can also optionally add a caption below any file you insert into your page to add more information if needed.
### Example of a file
{% file src="/files/JjxP2nmSa01O6lINhHqi" %}
This is a caption on a file.
{% endfile %}
### Uploading a file
You can manage uploaded files in the **Library** tab of your site section. The **Library** tab is beside **Pages** at the top of the left navigation.
To upload a file, drag and drop it into the **Drop your file or browse** section, or select it and use your system file dialog to select the file you want to upload.
{% hint style="warning" %}
GitBook allows you to upload files up to 100MB per file.
{% endhint %}
You can also add files to a page when you add an image block or an OpenAPI block. When you create one of these blocks, the **Library** tab opens, so you can either select a file, or upload a new file.
{% hint style="info" %}
**Tip:** You can also drag and drop images from your file system directly into the editor — or paste a copied image into your content. GitBook will automatically add them to the **Library** tab for the respective section, so you can view and manage them later.
{% endhint %}
### Renaming a file
To rename a file, open the **Actions menu** for the file, and click **Edit**. In the dialog prompt, enter the new name of your file.
### Deleting a file
To delete a file, open the **Actions menu** for the file and click **Delete**. After confirming in the dialog that you’re sure you want to delete the file, your file will be deleted.
{% hint style="warning" %}
**Note:** Make sure you update any pages that included your deleted file! File blocks that reference a deleted file will show an empty block, or *Could not load image* error.
{% endhint %}
### Replacing a file
If you have a file that simply needs updating to a new version, you can replace it. This will swap out the old file and put the new file in its place. Any blocks that previously referred to the old file will then refer to the new file.
To replace a file, open the **Action menu** for the file and click **Replace**. In the file replacement dialog that appears, choose the new file and wait for the upload indicator to complete. Your file automatically updates everywhere it appeared in your section.
This can be helpful if, for example, you've had a major product redesign and need to update outdated UI screenshots that appear on multiple pages. Replacing the original file would update the screenshot everywhere in your section, saving you time and effort.
{% hint style="info" %}
**Tip:** Once you've uploaded an image or a file, you can reference it anywhere in your section by creating an image or a file block and selecting it from the **Library** tab.
We recommend you do this rather than uploading the image again every time you want to include it, to make it easier to replace images later and to avoid having multiple files with the same name.
{% endhint %}
### Representation in Markdown
```markdown
{% file src="https://example.com/example.pdf" %}
This is a caption for the example file.
{% endfile %}
```
# Images
Add an image or a gallery of images to a page, add image variants for dark mode, and resize and align images to your needs
You can insert images into your page, then choose their size and whether to align them to the left, center, or right. You can also optionally include alt text and/or a caption on your image block.
{% hint style="info" %}
**Tip:** For accessibility purposes, we recommend setting alt text for your images.
{% endhint %}
### Example of an image block
Example of an image block with a caption
### Uploading an image
There are two ways to add images to your content:
1. Drag and drop the image from your file management system directly into an empty block on your page.
2. [Add an image block](/docs/create-content/blocks#inserting-a-new-content-block) to your page and use the **Select images** side panel that appears on the right of the window.
If you follow the second process, you can choose to upload a file, select a previously-uploaded file, paste an image URL or add an image from [Unsplash](https://unsplash.com/) using the built-in search.
{% hint style="warning" %}
GitBook allows you to upload images up to 100MB per file.
{% endhint %}
There's no set limit on the total number of assets in a section, though GitBook reserves the right to block accounts for abuse. For files larger than the upload limit, store them in a service like Google Drive or Dropbox and link to them from your page.
Animated gifs have a limit of 200 frames per file. Large files — gifs included — slow your page's loading time, so avoid uploading large files directly where you can.
#### Create an image gallery
Adding more than one image to an image block will create a gallery. To do this, open the block’s **Options menu** and choose **Add images…** to open the **Select images** side panel again.
To delete an image from a gallery, open the **Edit menu** on the image you want to delete and press the **Delete ⌫** key.
### Adding images for light & dark mode
You can set different images for the light and dark mode versions of your published site. GitBook will automatically display the correct image depending on the mode your visitor is in.
To add an image for dark mode, hover over your image, open the **Edit menu** and click **Replace image** .
In the drop-down menu, choose **Add image for Dark mode**. Once you’ve set this, you can replace either image from this same menu.
{% hint style="warning" %}
**Note:** GitBook doesn’t currently support light and dark mode images for certain cases, including page covers or image covers on [cards](/docs/create-content/blocks/cards).
{% endhint %}
### Light and dark mode images through GitHub/GitLab Sync
You can also add light and dark mode images in Markdown through HTML syntax (`` and ``).
For block images, use the `` HTML element with a `` and `` in it:
```html
Text before
Caption text
Text after
```
For inline images (images that sit inline with text), use the `` HTML element with a `` in it:
```html
Text before the image
and text after the image
```
{% hint style="warning" %}
**Note:** We don’t yet support [GitHub-only syntax](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/) through `#gh-dark-mode-only` or `#gh-light-mode-only`.
{% endhint %}
### Resizing
To resize your image, hover over it and open the **Edit menu** . Click the **Size** button to change the size of your image from the available options.
Resize an image
* **Small** – 25% of the image size
* **Medium** – 50% of the image size
* **Large** – 75% of the image size
* **Fit** – Removes all size specifications and displays either at full size or capped at a maximum width of **735** **pixels** for larger images.
If your image is wider than the editor, GitBook will limit the image’s width to the editor’s width instead, and resizing will be based on this limit.
{% hint style="info" %}
**Note:** When resizing images in an image gallery, the results can differ from resizing an individual image.
{% endhint %}
### Resizing images through Git Sync
If you want more control over the sizing of your image, you can specify the exact size using Markdown in GitHub or GitLab.
When we export an image, we use the HTML tag ``. As per the specifications, we can specify the dimensions of the image using the `width` and `height` attributes, which only accept values in pixels or a combination of a number and a `%` sign.\
\
Valid variants for specifying the image dimensions are:\
\
`` Sets the image to 100 pixels wide\
`` Sets the image to full size (although this will be limited by the editor)
### Aligning images
By default, image blocks will show your image at its full size, aligned centrally.
To change the alignment of an image, open the block’s **Options menu** and choose the alignment you want. This will only affect images that are narrower than the editor, or images you’ve [resized](#resizing).
### Framing images
You can add a frame to image blocks to give your images a consistent look and visually separate them from their surrounding content.
Framed images can have captions, and show a subtle grid behind the caption.
To add a frame to an image, hover over it, open the block’s **Options menu** and enable the **With frame** toggle.
{% hint style="info" %}
**Good to know:** You can only frame single images in a block. Image blocks that contain multiple images and inline images cannot have frames.
{% endhint %}
### Representation in Markdown
```markdown
//Simple Block
//Block with Caption
//Block with Alt text
//Block with Caption and Alt text
GitBook Logo
// Block with framed image
//Block with different image for dark and light mode, with caption
Caption text
```
### Why is my image not loading?
A "could not load image" error means the image was changed or deleted at its source. If you embedded an image by URL rather than uploading it, GitBook relies on that URL — if the image moves or disappears from the source, it stops displaying on your page.
To resolve it, upload the image directly to GitBook, or update the URL if the image's location changed. The error can also appear when you copy an image from one section to another, because each section has its own file directory — re-upload the image in the new section.
You can review all files uploaded to a section in the **Library** tab, beside **Pages** at the top of the table of contents.
# Embedded URLs
Embed videos, music and more directly into your page with a URL
To add an embedded URL, paste the link of the content you want to embed and press `Enter`.
### Videos
{% embed url="" %}
{% hint style="info" %}
**Note:** You can choose to auto-play and loop YouTube and Vimeo embeds by adding `?autoplay=1&loop=1` to the end of your video’s URL.
{% endhint %}
#### Video files
Uploaded video files — such as MP4s — don't play inline; they appear as links that visitors can click to open or download. To show a playable video on your page, upload the video to a publicly accessible platform such as YouTube or Google Drive, then paste the link into an embed block. Private URLs won't display on your page.
### Codepen
{% embed url="" %}
### Spotify
{% embed url="" %}
### Representation in Markdown
```markdown
{% embed url="URL_HERE" %}
```
### FAQ
Why isn't my URL working?
Your content must be publicly available. For Google Docs, select the *Anyone with the link* sharing setting.
GitBook embeds URLs through [Iframely](https://iframely.com/domains). Confirm that Iframely supports your provider, then [test your URL with Iframely](https://iframely.com/try).
GitBook can't embed external HTML `
.png?alt=media&token=a5c0993c-f49a-4911-8297-6e76f0435bcb)
.png?alt=media&token=69805dbf-4ce7-4a6b-ac4d-43fc958d62c4)
```
{% endcode %}
It renders as follows: Here is an inline image: 
.png?alt=media&token=a1a7dbe0-f83d-4551-8f38-5665d02221bd)
image
* This is a second line using an unordered list and color
{% endhint %}
To add a heading to your hint, you need to create a heading block as the the first block in the hint.
### Representation in Markdown
```markdown
{% hint style="info" %}
**Info hints** are great for showing general information, or providing tips and tricks.
{% endhint %}
{% hint style="success" %}
**Success hints** are good for showing positive actions or achievements.
{% endhint %}
{% hint style="warning" %}
**Warning hints** are good for showing important information or non-critical warnings.
{% endhint %}
{% hint style="danger" %}
**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
{% endhint %}
{% hint style="info" icon="books" %}
This hint block has a custom icon.
{% endhint %}
{% hint style="info" %}
## This is a H2 heading
This is a line
This is an inline 
image
- This is a second line using an unordered list and color
{% endhint %}
```
# Quotes
Add a quote block to a page to highlight copy you’re adding from elsewhere, or to draw attention to a specific part of your text
Quotes are useful when you want to include something from another source.
Start a quote by typing `>` followed by pressing `Space` in an empty paragraph, or use the[ insert palette](/docs/create-content/blocks#inserting-a-new-content-block). You can also convert a paragraph block to a quote by highlighting the entire paragraph and hitting `>`.
### Example of a quote
> "No human ever steps in the same river twice, for it’s not the same river and they are not the same human." — *Heraclitus*
### Representation in Markdown
{% code overflow="wrap" %}
```markdown
> "No human ever steps in the same river twice, for it’s not the same river and they are not the same human." — _Heraclitus_
```
{% endcode %}
# Code blocks
Add a code block to a page to include sample code, configurations, code snippets and more
You can add code to your GitBook pages using code blocks.
When you add a code block, you can choose to [set the syntax](#set-syntax...), [show line numbers](#with-line-numbers), [show a caption](#with-caption), and [wrap the lines](#wrap-code). It’s also easy to [copy the contents of a code block to the clipboard](#copying-the-code), so you can use it elsewhere
A code block may be useful for:
* Sharing configurations
* Adding code snippets
* Sharing code files
* Showing usage examples of command line utilities
* Showing how to call API endpoints
* And much more!
### Add a code block
1. To add a code block, place your cursor on an empty line and type `/`.
2. In the quick insert menu, select **Code block**.
3. GitBook inserts the block and places your cursor inside it, ready for you to paste or type code.
### Example of a code block
{% code title="index.js" overflow="wrap" lineNumbers="true" %}
```javascript
import * as React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(
