+
+## Contributing
+
+We encourage contributions to our public documentation, provided they are accurate, helpful, and add value to our users. Whether it’s fixing a typo, clarifying content, or adding new insights, every improvement makes a difference. Your input helps ensure our resources remain reliable and effective for the community.
+
+### Open a pull request
+
+If you find something you'd like to change, follow these steps to create a PR and contribute to our documentation:
+
+1. **Fork this repository**: Click the "Fork" button in the top-right corner of this page to create a copy of the repository in your GitHub account.
+
+2. **Clone the fork**: Clone the forked repository to your local machine using a command like `git clone [repository URL]`.
+
+3. **Make your change**: Open the file you'd like to change in a text or code editor, fix it, and save your changes.
+
+4. **Commit your change**: Create a commit with a clear message, such as `git commit -m "Fix typo in [file name]"`.
+
+5. **Push your branch**: Push your changes to a new branch in your forked repository with `git push origin [branch name]`.
+
+6. **Open a pull request**: Go to the original repository, click "New Pull Request," and select your branch as the source.
+
+7. **Submit the PR**: Add a short description of your changes, then submit the pull request for review.
+
+We review all pull requests submitted to this repository and will follow up with additional information if necessary.
+
+## Badges
+
+
+
+
+
+
+
+### Markdown
+
+```md
+[](https://gitbook.com/)
+```
+
+### HTML
+
+```html
+
+
+
+```
+
+## Other GitBook projects
+
+If you're interested in contributing or learning more about the other projects GitBook is working on, head to our [GitHub profile](https://github.com/GitbookIO) or take a look at our popular projects below.
+
+- [GitBook](https://github.com/GitbookIO/gitbook)
+- [Integrations](https://github.com/GitbookIO/integrations)
+
+## Contributors
+
+
+
+
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000..e43b0f98
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/README.md b/README.md
index a149247b..c9ccbb5d 100644
--- a/README.md
+++ b/README.md
@@ -1,33 +1,17 @@
---
-icon: hand-wave
description: >-
- GitBook is a platform for capturing and documenting technical knowledge — from
- product docs, to internal knowledge bases and APIs.
-layout:
- title:
- visible: true
- description:
- visible: true
- tableOfContents:
- visible: true
- outline:
- visible: true
- pagination:
- visible: true
+ Create and publish beautiful documentation your users will love. GitBook has
+ all the tools you need to create everything from product guides to API
+ references and beyond.
+icon: book-open
---
-# Welcome
+# GitBook Documentation
-We want to help **teams to work more efficiently** with a simple but powerful platform that helps them **share their knowledge**.
+At GitBook, our mission is to provide a **user-friendly** and **collaborative** solution for creating, editing, and sharing product and API documentation.
-Our mission is to make a **user-friendly** and **collaborative** product for everyone to create, edit and share knowledge through documentation.
+Sign upQuickstart
### Discover GitBook
-
Content editor
Edit pages, collections, content, and more in GitBook.
### How to access your personal account settings
@@ -70,7 +64,7 @@ GitBook can provide you with two types of [notifications](../collaboration/notif
Organization
-Your personal account could be a member of any number of organizations, and this tab can be considered a shortcut to the [organization settings page](organization-management.md) for each organization. You can also create a new organization from this page.
+Your personal account could be a member of any number of organizations, and this tab can be considered a shortcut to the [organization settings page](organization-settings.md) for each organization. You can also create a new organization from this page.
diff --git a/account-management/billing-faq/cancelling-a-plan.md b/account-management/billing-faq/cancelling-a-plan.md
index ce8564fa..7b9e6ca6 100644
--- a/account-management/billing-faq/cancelling-a-plan.md
+++ b/account-management/billing-faq/cancelling-a-plan.md
@@ -9,7 +9,7 @@ Only administrators can access an organization’s billing settings to cancel a
If your mind is made up, here’s how to cancel your plan:
-1. Go to the organization’s settings page. You can click on the settings icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
+1. Go to the organization’s settings page. You can click on the settings icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
2. Click on the **billing** tab. This will take you to a billing page hosted on Stripe, our payment processor.
diff --git a/account-management/cancelling-a-plan.md b/account-management/cancelling-a-plan.md
index a9e66753..21b143cb 100644
--- a/account-management/cancelling-a-plan.md
+++ b/account-management/cancelling-a-plan.md
@@ -1,19 +1,19 @@
---
icon: xmark
+description: Cancel your subscription.
---
# Subscription cancellations
-If you’re thinking about cancelling a plan because you’re running into any issues while using GitBook, please [contact the support team](../help-and-faq/faq/support.md) first! We’d love to help you.
+If you’re thinking about cancelling a plan because you’re running into any issues while using GitBook, please [contact](https://gitbook.com/docs/help-center/support/how-do-i-contact-support) our support team! If there’s anything we can solve, we’re here to help.
-{% hint style="info" %}
-**Permissions**\
-Only administrators can access an organization’s billing settings to cancel a plan.
-{% endhint %}
+Here’s how to cancel your plan:
+
+1. Go to the organization’s settings page. You can click on the settings
-If your mind is made up, here’s how to cancel your plan:
+
-1. Go to the organization’s settings page. You can click on the settings icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
+ icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
2. Click on the **billing** tab. This will take you to a billing page hosted on Stripe, our payment processor.
3. Click the **cancel plan** button.
4. On the following page, confirm by clicking a second button labelled **cancel plan**.
@@ -22,8 +22,8 @@ If your mind is made up, here’s how to cancel your plan:
Once your plan has been cancelled, as per our [billing policy](plans/billing-policy.md), it will remain active until the end of your current billing period. Your subscription will no longer renew, and the plan’s cancellation will take full effect at the end of that billing period.
{% endhint %}
-### Changed your mind? No problem!
+### Change your mind?
After cancelling and before the end of your current billing period, you have the option to renew your plan! Just click the **renew plan** button shown below (and again on the next page to confirm) and your subscription will once again renew automatically.
-Or, if you change your mind _after_ the end of the billing period, you can purchase a new plan.
+After this, if you’d like to use GitBook again on a paid plan, you can purchase a new plan.
diff --git a/account-management/member-management/README.md b/account-management/member-management/README.md
index 8117cbc9..caf7e119 100644
--- a/account-management/member-management/README.md
+++ b/account-management/member-management/README.md
@@ -7,29 +7,12 @@ description: Learn how to manage access to content for members of your organizat
You can [invite and remove members](invite-members-to-your-organization.md) from your organization, manage members’ content access through [roles](roles.md), and manage [teams](teams.md) of members from the members’ page in your organization’s settings.
-{% hint style="info" %}
-**Permissions**
-
-**Admins** can invite and remove members, change members’ roles, and manage teams. **Creators** can manage permissions at a content level (collection or space).\
-**Team owners** can manage members of the team they have ownership of.
-{% endhint %}
-
-{% embed url="https://www.youtube.com/watch?v=XdocAjHKuLU" %}
-
## Members & permissions
-Shows each person’s role, last seen date, and [SSO](../sso-and-saml/sso-and-saml.md) status, if applicable. You’ll also see an overview of the [spaces](../../content-editor/editor/content-structure/what-is-a-space.md) they can access and, if you’re on the Pro plan, how many [teams](teams.md) they’re part of.
-
-
Members in a GitBook Organization.
+Shows each person’s role, last seen date, and SSO status, if applicable. You’ll also see an overview of the [spaces](../../creating-content/content-structure/space.md) they can access and, if you’re on the Pro plan, how many [teams](teams.md) they’re part of.
Click the **Teams** or **Access** listings for any member to jump to a list of all those teams and spaces.
You can also click on any member to open their **individual member page**. Here, you can see more information about them, including their join date and active status.
Select the **Teams** and **Spaces** tabs to see a list of the [teams](teams.md) they’re a member of, and the spaces they have access to — as well as their access level for those specific spaces.
-
-
Member Space permissions
-
-### Learn more about:
-
-
Inviting members
Learn more about inviting or removing members to your organization
diff --git a/account-management/member-management/invite-members-to-your-organization.md b/account-management/member-management/invite-members-to-your-organization.md
index 496b41cd..0a359bdb 100644
--- a/account-management/member-management/invite-members-to-your-organization.md
+++ b/account-management/member-management/invite-members-to-your-organization.md
@@ -19,16 +19,10 @@ Invite links are tied to specific [roles](roles.md) – and you can create (and
You can directly invite members in the members’ section of your organization settings. Enter their email(s), select their default role, and click **continue**. Each member will receive an email that will allow them to sign up to GitBook and instantly join your organization.
-
Invite links to a space
-
#### Email domain
You can allow all users with a specific email domain to join your organization.
-{% hint style="info" %}
-Please note that this can result in quick member growth, leading to higher charges.
-{% endhint %}
-
### Removing members
#### Leaving an organization
diff --git a/account-management/member-management/permissions-and-inheritance.md b/account-management/member-management/permissions-and-inheritance.md
index 8fa9f070..3b0b52cc 100644
--- a/account-management/member-management/permissions-and-inheritance.md
+++ b/account-management/member-management/permissions-and-inheritance.md
@@ -8,8 +8,6 @@ When you add a member to your organization, you set [their default role](roles.m
### Managing inheritance
-
permissions inheritance
-
Any time you create a collection or a space, you’ll be able to set the type of inheritance you want. You have three broad options when setting the inheritance for a piece of content:
### Inherit
diff --git a/account-management/member-management/roles.md b/account-management/member-management/roles.md
index de26ca38..450774d0 100644
--- a/account-management/member-management/roles.md
+++ b/account-management/member-management/roles.md
@@ -2,10 +2,10 @@
When adding members to your organization, you can give them a **default role**. This role will apply to any content that inherits its permissions from the organization.
-
Invite members to your GitBook organization.
-
{% hint style="info" %}
-Understanding default roles is key to getting the most out of how GitBook handles permission management. Check out our documentation on [**permissions and inheritance**](permissions-and-inheritance.md) for a full overview of how permissions cascade throughout content in GitBook.
+Understanding default roles is key to getting the most out of how GitBook handles permission management.
+
+See our documentation on [**permissions and inheritance**](permissions-and-inheritance.md) for a full overview of how permissions cascade throughout content in GitBook.
{% endhint %}
### Roles in GitBook
@@ -46,7 +46,7 @@ A reader is the most basic role in GitBook: it gives read-only access.
Commenter
-Commenters have the same read-only access as readers, but they’re also able to leave comments against content and spaces (find our more about how that works in our [comments](../../collaboration/comments-discussion.md) documentation).
+Commenters have the same read-only access as readers, but they’re also able to leave comments against content and spaces (find our more about how that works in our [comments](../../collaboration/comments.md) documentation).
**Commenter is one of our two advanced member roles, available only on the Pro or Enterprise plan.**
@@ -56,7 +56,7 @@ Commenters have the same read-only access as readers, but they’re also able to
Editor
-Editors are able to read and comment, just like a commenter, but they’re also able to edit content in a couple of ways. Firstly, for spaces that are **open** for [live edits](../../content-editor/editing-content/live-edits.md), editors can edit the content directly. Secondly, for spaces that have live edits **locked**, editors can create and submit [change requests](../../collaboration/change-requests.md). Editors cannot merge change requests.
+Editors are able to read and comment, just like a commenter, but they’re also able to edit content in a couple of ways. Firstly, for spaces that are **open** for [live edits](../../collaboration/live-edits.md), editors can edit the content directly. Secondly, for spaces that have live edits **locked**, editors can create and submit [change requests](../../collaboration/change-requests.md). Editors cannot merge change requests.
@@ -74,9 +74,9 @@ Reviewers have all the same permissions as an editor however, they can also merg
Creator
-Creators are essentially content-level admins. They can create, delete, and publish spaces and collections; manage permissions at a content level.
+Creators are essentially content-level admins. They have all the same permissions as a reviewer, however they can also create and delete spaces, collections and sites, merge change requests and manage permissions at a content level.
-If a creator is also a creator or admin in another GitBook organization, they have the ability to move content between organizations.
+If a creator is also a creator or admin in another GitBook organization, they have the ability to [move content between organizations](../../creating-content/content-structure/space.md#move-a-space).
@@ -84,8 +84,8 @@ If a creator is also a creator or admin in another GitBook organization, they ha
Admin
-An admin is like a super-user for your organization – they have full access! Set someone as an admin if you’re comfortable with them making changes that can impact billing, managing members, and generally just being in control of all areas of the organization.
+An admin is like a super-user for your organization — they have full access! Set someone as an admin if you’re comfortable with them making changes that can impact billing, managing members, and generally just being in control of all areas of the organization.
-If an admin is also a creator or admin in another GitBook organization, they have the ability to move content between organizations.
+If an admin is also a creator or admin in another GitBook organization, they have the ability to [move content between organizations](../../creating-content/content-structure/space.md#move-a-space).
diff --git a/account-management/member-management/teams.md b/account-management/member-management/teams.md
index 1d0e5fdf..30a040d4 100644
--- a/account-management/member-management/teams.md
+++ b/account-management/member-management/teams.md
@@ -12,8 +12,6 @@ You can create, edit, and remove teams in the **Teams** section of your organiza
To find this, click on settings icon in the bottom of your window. Choose organization settings for your desired organization, then click the Teams option in the sidebar.
-
Team Settings Page.
-
On this page, you can view and search your current teams, or click one to open the team details page and see more information about it and its members.
### Managing team members
@@ -23,10 +21,6 @@ You can manage team members in two ways:
1. Click on a specific member in **Members & permissions** to open their member page, and select the **Teams** tab. Click the vertical ellipsis and you can remove them from the team immediately, or choose **Manage team.**
2. In the **Teams** section, click on the number of members in the list to open the team details page. You can then use multi-select on the member list to select and remove team members or add more with the button at the top.
-
Manage team member modal
-
### Team owners
Team owners (available only in Enterprise plans) allow you to hand over management of a specific team to a selected member. Team owners can add and remove members from the team they are an owner of by clicking on the organization settings, then teams. They will not have access to any other organization settings, including managing other teams.
-
-
Set a team owner for a team.
diff --git a/account-management/organization-management.md b/account-management/organization-management.md
deleted file mode 100644
index c9d15c94..00000000
--- a/account-management/organization-management.md
+++ /dev/null
@@ -1,99 +0,0 @@
----
-icon: sitemap
----
-
-# Organization settings
-
-View and manage the settings for your GitBook organization. These include member management, sign-in methods, integrations, billing and plans.
-
-{% hint style="info" %}
-**Permissions**\
-Only administrators can access the organization settings.
-{% endhint %}
-
-
Organization Settings Page.
-
-### How to access the settings for an organization
-
-Click on the **settings** icon, then click on **\[organization name] settings**. This will take you to the general tab of that organization’s settings page, and you’ll see additional tabs containing further settings on the left-hand side.
-
-
-
-General
-
-**Organization profile**
-
-You can update the logo and the name of the organization.
-
-**GitBook AI features**
-
-[GitBook’s AI](../content-editor/searching-your-content/gitbook-ai.md)-powered search lets your team members ask questions about your content in natural language. You can also enable GitBook AI for published content in the space [customization ](../published-documentation/customization/)panel. GitBook AI is available as part of our Pro and Enterprise plans.
-
-**Publishing**
-
-Each published GitBook space that lives within your organization’s library will have a domain in two parts:
-
-1. `[something].gitbook.com` (this is the GitBook subdomain) **or** your own custom subdomain
-2. `/[spaceURL]` (this is set within the settings for the space itself)
-
-You can update the GitBook subdomain and a custom domain here, as well as the default content, which is the space that visitors will see if they navigate to your GitBook subdomain directly.
-
-**Actions**
-
-From this section you can delete the organization. **Note: there is no turning back if you delete an organization!** All associated data will be deleted as well. If you want to keep any spaces or collections owned by the organization, make sure to first [move](https://docs.gitbook.com/getting-started/organizing-content/what-is-a-space#moving-a-space) them to another library.
-
-
-
-
-
-Members
-
-**Members tab**
-
-[Members](member-management/) can be added to and removed from the organization as needed. You can also update the [role](member-management/roles.md) for each member.
-
-**Teams tab**
-
-[Teams](member-management/teams.md) are a way to group members within an organization. You can then grant access to certain things to anyone who is a member of a given team.
-
-
-
-
-
-SSO
-
-**Email domains**
-
-For any domains that you specify, anyone with an email address on those domains will immediately be able to access the organization upon signing up for a GitBook account. You can decide what [role](member-management/roles.md) these members should have by default.
-
-**SAML**
-
-For organizations on our Enterprise plan, you can configure your SSO with any [SAML](sso-and-saml/saml/) solution, to give your members access to GitBook through an identity provider (IdP) of your choice. [Contact sales](mailto:sales@gitbook.com) if you’re interested in upgrading to Enterprise!
-
-
-
-
-
-Integrations
-
-You can check which [integrations](../integrations/overview.md) are installed for your organization and [install new integrations](../integrations/install-an-integration.md) from this page.
-
-
-
-
-
-Plans
-
-From this page you can view your current plan and switch from one plan to another. The toggle at the top of the page enables you to switch between viewing the prices for our plans paid yearly (with 2 months free!) or monthly, and you can then use the upgrade/downgrade button under the name of each plan to select your new plan.
-
-Please see our [billing policy](plans/billing-policy.md) for information about how charges are calculated when you make a change during the middle of a billing period.
-
-
-
-
-
-Billing
-
-The billing tab takes you to our payment provider, Stripe. On their website you can securely manage your payment method and billing information. You can also [cancel your plan](cancelling-a-plan.md). If a plan has been cancelled but you change your mind before the end of the billing period, you can renew the plan to have it continue without any lapse in service.
-
-
diff --git a/account-management/organization-settings.md b/account-management/organization-settings.md
new file mode 100644
index 00000000..b5138368
--- /dev/null
+++ b/account-management/organization-settings.md
@@ -0,0 +1,90 @@
+---
+icon: sitemap
+---
+
+# Organization settings
+
+View and manage the settings for your GitBook organization. These include member management, sign-in methods, integrations, billing and plans.
+
+
Your organization settings page.
+
+### How to access the settings for an organization
+
+Click on the **settings** icon, then click on **\[organization name] settings**. This will take you to the general tab of that organization’s settings page, and you’ll see additional tabs containing further settings on the left-hand side.
+
+
+
+General
+
+**Organization profile**
+
+You can update the logo and the name of the organization.
+
+**GitBook AI features**
+
+[GitBook’s AI](../creating-content/searching-your-content/gitbook-ai.md)-powered search lets your team members ask questions about your content in natural language. You can also enable GitBook AI for published content in the space [customization ](../publishing-documentation/customization/)panel.
+
+**Publishing**
+
+Each published GitBook space that lives within your organization’s library will have a domain in two parts:
+
+1. `[something].gitbook.com` (this is the GitBook subdomain) **or** your own custom subdomain
+2. `/[spaceURL]` (this is set within the settings for the space itself)
+
+You can update the GitBook subdomain here, as well as the default content, which is the space that visitors will see if they navigate to your GitBook subdomain directly.
+
+Note: GitBook subdomains are a legacy feature, and you may not have access to change your subdomain at the time of reading this doc. Please refer to [custom domain setup](../publishing-documentation/custom-domain.md) and [site sections](../publishing-documentation/site-structure/site-sections.md) to learn more about structuring your docs with custom URLs.
+
+**Actions**
+
+From this section you can delete the organization. **Note: there is no turning back if you delete an organization!** All associated data will be deleted as well. If you want to keep any spaces or collections owned by the organization, make sure to first [move](../creating-content/content-structure/space.md#move-a-space) them to another library.
+
+
+
+
+
+Members
+
+**Members tab**
+
+[Members](member-management/) can be added to and removed from the organization as needed. You can also update the [role](member-management/roles.md) for each member.
+
+**Teams tab**
+
+[Teams](member-management/teams.md) are a way to group members within an organization. You can then grant access to certain things to anyone who is a member of a given team.
+
+
+
+
+
+SSO
+
+**Email domains**
+
+For any domains that you specify, anyone with an email address on those domains will immediately be able to access the organization upon signing up for a GitBook account. You can decide what [role](member-management/roles.md) these members should have by default.
+
+**SAML**
+
+For organizations on our Enterprise plan, you can configure your SSO with any SAML solution, to give your members access to GitBook through an identity provider (IdP) of your choice. [Contact sales](mailto:sales@gitbook.com) if you’re interested in upgrading to Enterprise!
+
+
+
+
+
+Integrations
+
+You can check which integrations are installed for your organization and [install new integrations](../integrations/install-an-integration.md) from this page.
+
+
+
+
+
+Billing
+
+From this page you can view your current plan and switch from one plan to another. The toggle at the top of the page enables you to switch between viewing our annual prices (2 months free) or monthly, and you can then use the upgrade/downgrade button under the name of each plan to select your new plan.
+
+Please see our [billing policy](plans/billing-policy.md) for information about how charges are calculated when you make a change during the middle of a billing period.
+
+The Manage Billing button takes you to our payment provider, Stripe. Here you can securely manage your payment method and billing information. You can also [cancel your plan](cancelling-a-plan.md). If a plan has been cancelled but you change your mind before the end of the billing period, you can renew the plan to have it continue without any lapse in service.
+
+
diff --git a/account-management/overview.md b/account-management/overview.md
deleted file mode 100644
index 1398b31b..00000000
--- a/account-management/overview.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-description: Manage the team you collaborate with in GitBook.
-icon: bullseye-arrow
----
-
-# Overview
-
-GitBook allows you to work as a team on the content you’re creating.
-
-### Learn more about
-
-
diff --git a/account-management/plans/README.md b/account-management/plans/README.md
index c1a0cffc..40bd50a6 100644
--- a/account-management/plans/README.md
+++ b/account-management/plans/README.md
@@ -1,33 +1,14 @@
---
+description: Learn about the differences in plans GitBook has.
icon: money-check-dollar-pen
-description: Learn about the plans we offer for your GitBook organizations.
---
-# Choose your plan
+# Plans
-There are 2 types of plans in GitBook - User plans and Site plans. Depending on your organization’s setup continue reading to learn more about the different types of plans GitBook offers.
+GitBook allows you to publish documentation on different plans. Each site plan contains different features — including advanced customization, AI features, and more. You can pay for additional users on any paid plan.
-You can view our [pricing page](https://www.gitbook.com/pricing) to find more information about each plan.
+Find the full feature table on our pricing page.
-{% hint style="info" %}
-**Permissions**\
-Only administrators can access an organization’s billing settings.
-{% endhint %}
+Visit pricing page
-### User Plans
-
-User plans determine the number of users you have, along with the user-specific features your users will have.
-
-
Free
Free plan with all the essential features to scale public projects.
Plus
Ideal for small teams that want to collaborate and document publicly.
Pro
Ideal for multi-role teams who want advanced publishing and collaboration options.
Enterprise
Ideal for teams of 20+ with more security and compliance needs.
-
-### Site Plans
-
-Site plans are based off of the type of features you need in your published site.
-
-
Basic
For simple docs sites with basic customization needs.
Premium
For branded docs sites with standard sharing requirements.
Ultimate
For secure docs sites that require authentication before viewing.
-
-
-
-{% hint style="success" %}
-Compare all features included in each plan by navigating to our [pricing page](https://www.gitbook.com/pricing#pricingTable).
-{% endhint %}
+
Cover image
Cover image (dark)
Basic
For simple docs sites with basic customization needs.
diff --git a/account-management/plans/apply-for-the-non-profit-open-source-plan.md b/account-management/plans/apply-for-the-non-profit-open-source-plan.md
deleted file mode 100644
index ff18836a..00000000
--- a/account-management/plans/apply-for-the-non-profit-open-source-plan.md
+++ /dev/null
@@ -1,120 +0,0 @@
----
-description: Apply for our Open Source plan in GitBook.
-layout:
- title:
- visible: true
- description:
- visible: false
- tableOfContents:
- visible: true
- outline:
- visible: true
- pagination:
- visible: true
----
-
-# Apply for the Community plan
-
-We welcome applications for our Community plan from organizations that meet certain criteria. Broadly, these fall into one of three categories:
-
-1. Non-profit organizations
-2. Open source organizations
-3. Education-related groups
-
-{% hint style="info" %}
-If you won’t need to collaborate with others and/or can use [Git Sync](../../integrations/git-sync/) to collaborate via GitHub and GitLab then your needs should be covered by our Free plan!
-
-If you want to publish a docs site for free too, you can choose from either a Basic site with limited features, or [a Sponsored site](sponsored-site-plan.md) which has more features and earns you funding through small, relevant ads. See [our open source page](https://www.gitbook.com/solutions/open-source) for more details on these plans.
-{% endhint %}
-
-If you will **need** to collaborate with others, then please continue reading.
-
-## Our criteria
-
-### For all
-
-{% hint style="warning" %}
-We apologize in advance if we reject your application. We don’t have the resources to share details. We’ll do our best to give you some context if possible, but please check our criteria below to figure out what might be wrong. Please note you can reapply at any time if you are able to adjust and meet our criteria.
-{% endhint %}
-
-Your organization should **not**:
-
-* be a church, affiliated with one, or promote any specific religion.
-* be a school, college, university, etc. (but it can be a student group, lab group, course group, etc.).
-* be a government office, ministry, or function (but can be a small municipality local office).
-* be a private foundation.
-* have political affiliations.
-* promote a dogma.
-* promote a religious position as part of its activity.
-* promote discrimination of any kind, on the basis of gender (identity or expression), race, ethnicity, political or religious opinion, sexual orientation, or anything else.
-
-### Criteria for non-profit organizations
-
-Your organization **needs to**:
-
-* Be a company with an official non-profit status.
-* Share a valid charitable status (501(c) or equivalent for your country).
-
-### Criteria for open source projects
-
-Your Git repository **must**:
-
-* Exist _publicly_ on GitHub or GitLab.
-* Be a truly open source project that is not associated with a profitable or venture-backed company.
-* Not be an empty repository.
-* Not be a fork with no activity of its own.
-* Have a `README.md` file that clearly explains what the software is about.
-* Have a `CONTRIBUTING.md` file that explains how to contribute to the project.
-* Have a `LICENSE` file with [a valid OSS license](https://choosealicense.com/).
-* Have a `CODE_OF_CONDUCT.md` file.
-* Make it easy for others to [contribute](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github#finding-good-first-issues).
-
-### Criteria for education-related groups
-
-* The organization _must not_ represent a school, college, or university as a whole.
-* The organization _may_ represent a small group related to a school, college, or university.
-* You _may_ be a small student group or a teacher organizing a course for a small group of students.
-
-{% hint style="info" %}
-Individual students who want to keep their personal and course notes should use our **Free** plan. This plan provides unlimited private spaces at no cost, without needing to apply for the Community plan, and if you want to publish docs sites you can select a Basic or Sponsored site for free.
-{% endhint %}
-
-## How to apply
-
-1. **Sign up or sign in**\
- Start by [signing up](https://app.gitbook.com/join) for a GitBook account if you don’t have one yet, or [signing in](https://app.gitbook.com) if you do.
-2. **Choose an organization**\
- Decide which organization you would like the Community plan to be applied to. This could be one that you’ve already created, or you might want to create a new organization.\
- &#xNAN;_(To create a new organization, click the switch organization toggle near the top of the_ [_sidebar_](https://docs.gitbook.com/getting-started/overview#sidebar)_, then click **create an organization**, and follow the prompts.)_
-3. **Get the organization’s URL**\
- In the [sidebar](https://docs.gitbook.com/getting-started/overview#sidebar), click on the name of the organization you chose in step 2. Copy or make a note of the URL in your browser. It will be in the format `app.gitbook.com/o/[string]/home`, where `[string]` will be a unique string of letters and numbers used to identify that organization.
-4. **Contact us via our messenger on** [**our website**](https://www.gitbook.com/contact)\
- Select ’Contact Support’ and then ’I have a question about pricing’ then ’I want to apply to the Community plan’, or alternatively send us an email with the required info to support@gitbook.com
-
-### Submitting your application via email
-
-Depending on which type of organization you are applying for, please follow the relevant steps listed below.
-
-{% tabs %}
-{% tab title="Non-profit organizations" %}
-* Briefly describe the purpose of your non-profit organization.
-* Share a link to your organization’s public website.
-* Attach your non-profit organization’s valid 501(c) or equivalent documentation for your country.
-* Include the link to your organization. Finding this link is described in step 3 of the section above.
-{% endtab %}
-
-{% tab title="Open source projects" %}
-* Briefly describe the purpose of your open source project.
-* Share a link to your public Git **repository** on GitHub or GitLab.
-* Include the link to your organization. Finding this link is described in step 3 of the section above.
-{% endtab %}
-
-{% tab title="Small education-related groups" %}
-* Ask each member of the group to create their own GitBook account using their school email address, and invite them to the organization. Please only send your application once this has been done.
-* Briefly describe your group and its purpose.
-* Share a link to a public website associated with your education group, if you have one.
-* Include the link to your organization. Finding this link is described in step 3 of the section above.
-{% endtab %}
-{% endtabs %}
-
-If you have any questions, feel free to [contact our support team](../../help-and-faq/faq/support.md).
diff --git a/account-management/plans/billing-policy.md b/account-management/plans/billing-policy.md
index ae8b9178..f5d9b840 100644
--- a/account-management/plans/billing-policy.md
+++ b/account-management/plans/billing-policy.md
@@ -1,13 +1,13 @@
# Billing policy
-We keep things fair by billing based on plan usage:
+Our billing process is structured to align charges with the level of plan usage:
-- You’ll be charged based on the number of members in your organization on the day that you upgrade to a paid plan, and on each day that the plan renews, either monthly or yearly.
-- You can make changes to the number of members in the organization at any time, and those changes will be reflected in your **next** bill on a prorated basis, whether you pay monthly or yearly.
-- The _one_ exception to the above is if you have chosen an annual plan and your changes result in a balance of over $240 on the Plus plan or over $450 on the Pro plan. _(For customers on our legacy plans, this would apply for a balance of over $300 on the Team plan or over $1000 on the Business plan.)_ If your balance exceeds the relevant amount, we will process a payment for the changes immediately.
+* You’ll be charged based on the number of members in your organization on the day that you upgrade to a paid plan, and on each day that the plan renews, either monthly or yearly.
+* You can make changes to the number of members in the organization at any time, and those changes will be reflected in your **next** bill on a prorated basis, whether you pay monthly or yearly.
+* The _one_ exception to the above is if you have chosen an annual plan and your changes result in a balance of over $240 on the Plus plan or over $450 on the Pro plan. _(For customers on our legacy plans, this would apply for a balance of over $300 on the Team plan or over $1000 on the Business plan.)_ If your balance exceeds the relevant amount, we will process a payment for the changes immediately.
{% hint style="info" %}
-We also encourage you to familiarise yourself with our [terms of service](https://policies.gitbook.com/terms). In particular, you may like to review the section about [payment](https://policies.gitbook.com/terms#k.-payment).
+We also encourage you to familiarise yourself with our [terms of service](https://gitbook.com/docs/policies/terms). In particular, you may like to review the section about [payment](https://gitbook.com/docs/policies/terms#id-3.-payment-terms).
{% endhint %}
## Pro rata pricing example
diff --git a/account-management/plans/community/README.md b/account-management/plans/community/README.md
new file mode 100644
index 00000000..d78b1db7
--- /dev/null
+++ b/account-management/plans/community/README.md
@@ -0,0 +1,110 @@
+---
+description: Apply for our Open Source plan in GitBook.
+---
+
+# Community plan
+
+We welcome applications for our community plan from organizations that meet certain criteria. Broadly, these fall into one of three categories:
+
+1. Non-profit organizations
+2. Open source organizations
+3. Education-related groups
+
+{% hint style="info" %}
+If you won’t need to collaborate with others and/or can use [Git Sync](../../../getting-started/git-sync/) to collaborate via GitHub and GitLab then your needs should be covered by our Free plan!
+
+If you want to publish a docs site for free too, you can choose from either a Basic site with limited features, or [a Sponsored site](sponsored-site-plan.md) which has more features and earns you funding through small, relevant ads. See [our open source page](https://www.gitbook.com/solutions/open-source) for more details on these plans.
+{% endhint %}
+
+If you will **need** to collaborate with others, then please continue reading.
+
+## Our criteria
+
+### For all
+
+{% hint style="warning" %}
+We apologize in advance if we reject your application. We don’t have the resources to share details. We’ll do our best to give you some context if possible, but please check our criteria below to figure out what might be wrong. Please note you can reapply at any time if you are able to adjust and meet our criteria.
+{% endhint %}
+
+Your organization should **not**:
+
+* be a church, affiliated with one, or promote any specific religion.
+* be a school, college, university, etc. (but it can be a student group, lab group, course group, etc.).
+* be a government office, ministry, or function (but can be a small municipality local office).
+* be a private foundation.
+* have political affiliations.
+* promote a dogma.
+* promote a religious position as part of its activity.
+* promote discrimination of any kind, on the basis of gender (identity or expression), race, ethnicity, political or religious opinion, sexual orientation, or anything else.
+* be a crypto currency related project
+
+### Criteria for non-profit organizations
+
+Your organization **needs to**:
+
+* Be a company with an official non-profit status.
+* Share a valid charitable status (501(c) or equivalent for your country).
+
+### Criteria for open source projects
+
+Your Git repository **must**:
+
+* Exist _publicly_ on GitHub or GitLab.
+* Be a truly open source project that is not associated with a for-profit or venture-backed company.
+* Not be an empty repository.
+* Not be a fork with no activity of its own.
+* Have a `README.md` file that clearly explains what the software is about.
+* Have a `CONTRIBUTING.md` file that explains how to contribute to the project.
+* Have a `LICENSE` file with [a valid OSS license](https://choosealicense.com/).
+* Have a `CODE_OF_CONDUCT.md` file.
+* Make it easy for others to [contribute](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github#finding-good-first-issues).
+
+### Criteria for education-related groups
+
+* The organization _must not_ represent a school, college, or university as a whole.
+* The organization _may_ represent a small group related to a school, college, or university.
+* You _may_ be a small student group or a teacher organizing a course for a small group of students.
+
+{% hint style="info" %}
+Individual students who want to keep their personal and course notes should use our **Free** plan. This plan provides unlimited private spaces at no cost, without needing to apply for the Community plan, and if you want to publish docs sites you can select a Basic or Sponsored site for free.
+{% endhint %}
+
+## How to apply
+
+1. **Sign up or sign in**\
+ Start by [signing up](https://app.gitbook.com/join) for a GitBook account if you don’t have one yet, or [signing in](https://app.gitbook.com) if you do.
+2. **Choose an organization**\
+ Decide which organization you would like the Community plan to be applied to. This could be one that you’ve already created, or you might want to create a new organization.\
+ &#xNAN;_(To create a new organization, click the switch organization toggle near the top of the_ [_sidebar_](https://gitbook.com/docs/getting-started/overview#sidebar)_, then click **create an organization**, and follow the prompts.)_
+3. **Get the organization’s URL**\
+ In the [sidebar](https://gitbook.com/docs/getting-started/overview#sidebar), click on the name of the organization you chose in step 2. Copy or make a note of the URL in your browser. It will be in the format `app.gitbook.com/o/[string]/home`, where `[string]` will be a unique string of letters and numbers used to identify that organization.
+4. **Contact us via our messenger on** [**our website**](https://www.gitbook.com/contact)\
+ Select ’Contact Support’ and then ’I have a question about pricing’ then ’I want to apply to the Community plan’, or alternatively send us an email with the required info to support@gitbook.com
+
+### Submitting your application via email
+
+Depending on which type of organization you are applying for, please follow the relevant steps listed below.
+
+{% tabs %}
+{% tab title="Non-profit organizations" %}
+* Briefly describe the purpose of your non-profit organization.
+* Share a link to your organization’s public website.
+* Attach your non-profit organization’s valid 501(c) or equivalent documentation for your country.
+* Include the link to your organization. Finding this link is described in step 3 of the section above.
+{% endtab %}
+
+{% tab title="Open source projects" %}
+* Briefly describe the purpose of your open source project.
+* Share a link to your public Git **repository** on GitHub or GitLab.
+* Include the link to your organization. Finding this link is described in step 3 of the section above.
+{% endtab %}
+
+{% tab title="Small education-related groups" %}
+* Ask each member of the group to create their own GitBook account using their school email address, and invite them to the organization. Please only send your application once this has been done.
+* Briefly describe your group and its purpose.
+* Share a link to a public website associated with your education group, if you have one.
+* Include the link to your organization. Finding this link is described in step 3 of the section above.
+{% endtab %}
+{% endtabs %}
+
+If you have any questions, feel free to contact our support team.
diff --git a/account-management/plans/community/sponsored-site-plan.md b/account-management/plans/community/sponsored-site-plan.md
new file mode 100644
index 00000000..ac69804a
--- /dev/null
+++ b/account-management/plans/community/sponsored-site-plan.md
@@ -0,0 +1,99 @@
+---
+description: >-
+ Learn more about how you can earn money from your documentation site with our
+ sponsored site plan.
+---
+
+# Sponsored site plan
+
+{% hint style="info" %}
+This site plan is only available to users on our [community plan](./).
+{% endhint %}
+
+
Learn more about the sponsored site plan in GitBook.
+
+The sponsored site plan lets you access all of GitBook’s best docs site features at no cost while displaying a small, relevant ad in the corner of your documentation site. Each view generates revenue for you, turning your documentation into a source of income.
+
+### Apply for the sponsored site plan
+
+The sponsored site plan is designed specifically for **open source projects**. Please not we do not accept cryptocurrency, web3 or related projects for this plan.
+
+View the steps below to learn how to publish your first sponsored site.
+
+{% stepper %}
+{% step %}
+**Create and publish a sponsored site**
+
+Begin by creating a new site from the site wizard and setting up your site with content. By default, any site created on the community plan will be eligible for the sponsored site plan.
+{% endstep %}
+
+{% step %}
+**Submit your site for ad review**
+
+Your site must be [published **publicly**](../../../publishing-documentation/publish-a-docs-site/public-publishing.md) for **seven days** before you can submit it for review.
+
+Head to your site’s settings, and scroll down to the **Ads and sponsorship** section. From here, review the ads checklist to make sure your site meets all the requirements before submitting.
+{% endstep %}
+
+{% step %}
+**Wait for review**
+
+After submitting your application, here’s what you can expect:
+
+* **Review process:** Your site will be reviewed, and you can expect an estimated review time of **up to seven days**. Please note that this timeline may be different based on processing delays.
+* **Final status update:** After the review, we’ll update your site’s status. Your site will either be marked as **approved** or **rejected**, depending on the review outcome. If approved, ads will be added to your site and you can start earning money!
+* If **rejected**, you’ll have the opportunity to update your site and submit for approval again.
+{% endstep %}
+{% endstepper %}
+
+### How it works
+
+Once your site is live, here’s how the sponsored site plan operates:
+
+* **Earning potential:** Every time someone views your documentation, a small, relevant ad will be displayed in the bottom corner of each page. You earn money from every view, which you can use to support ongoing development efforts.
+* **Ethical advertising:** At GitBook, we prioritize ethical advertising. Ads displayed on your site will never track or retarget your users, ensuring a respectful experience for your audience.
+* **Visibility of content:** Your content remains the focus. Only one small ad will appear on each page, ensuring that your documentation is always front and center.
+
+### FAQ
+
+
+
+Why was my site rejected?
+
+Your site may be rejected for the sponsored site plan for several reasons. Common reasons include, but are not limited to:
+
+* Your project is not an open source or not-for-profit project.
+* Your project is a cryptocurrency project.
+* The site is not published in English as it's **primary** language.
+* The site does not contain quality content.
+* The site does not reach a minimum number of page views per month.
+
+
+
+
+
+How much money do I earn per view?
+
+The CPM (cost per 1000) fluctuates, meaning there isn't a set $ amount per view.
+
+After your site is approved, you'll gain access to your ads dashboard, giving you more insights into how your site performs over time.
+
+
+
+
+
+What happens if I don't submit my site for review?
+
+The sponsored site plan allows you to use ultimate site features to get your site ready before submitting it for review.
+
+Any site not submitted for revierw after 1 month will automatically revert back to a free plan, and any ultimate site features used will be turned off, including things like custom domains, customizations, and more.
+
+
+
+
+
+What happens if I decide to switch back to a free site plan?
+
+The sponsored site plan includes features that are not available to sites on the free plan. Switching back to a free plan will effectively downgrade your site plan, meaning you may lose access to certain features.
+
+
diff --git a/account-management/plans/legacy-plans.md b/account-management/plans/legacy-plans.md
index 8205a4b8..a43be61b 100644
--- a/account-management/plans/legacy-plans.md
+++ b/account-management/plans/legacy-plans.md
@@ -1,30 +1,35 @@
---
-description: Learn about the differences between our current and legacy plans.
+description: Learn about the differences between our current and legacy pricing.
+hidden: true
---
-# Legacy plans
+# Legacy pricing
-### Legacy plans
+We’ve [updated our pricing model](https://www.gitbook.com/blog/new-site-sections#new-pricing-for-new-users) recently, to accommodate for many of the new features we’ve been releasing for published sites. Because of this, there is a chance you may still be on our old pricing model.
-If you’re subscribed to one of our legacy (**Team** or **Business**) plans, you have two options. You can:
+Some of the new features we are releasing are only available on our updated pricing plans. Please [contact support](https://gitbook.com/docs/help-center/support/how-do-i-contact-support) if you would like to learn more and upgrade your pricing.
-1. Remain subscribed to the legacy plan; or
-2. Switch to one of our new and improved pricing plans. If you choose this option, it will _not_ be possible to revert back to a legacy pricing plan later.
+You can [view our current plans](./) here.
-You can find the [full feature comparison](https://www.gitbook.com/pricing) for the new plans on our site, but here is a convenient comparison between the legacy and the new plans:
+### Updated pricing
-#### Team vs Plus
+We've made some changes to our plans to simplify publishing and better align features with site plans. Here's a summary:
-| Difference | Team | Plus |
-| --------------------------- | ---- | ----------------------------------- |
-| Publish a space as unlisted | Yes | No (moved to the Pro plan) |
-| Advanced customization | Yes | No (moved to the Pro plan) |
-| Minimum charge for 5 users | Yes | No (unlimited users, pay as you go) |
+* **Pro Plan**: No longer includes a monthly platform fee. You can purchase and publish sites without restrictions, even on the Free plan.
+* **Organization Plan**: Now focused exclusively on collaboration.
-#### Business vs Pro
+**Features Now Tied to Site Plans**
-| Difference | Business | Pro |
-| ----------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- |
-| [Visitor authentication](../../published-documentation/publish-a-docs-site/visitor-authentication/) feature | Yes | Yes (up to 100 sessions per month) |
-| Minimum charge for 20 users | Yes | No (unlimited users, pay as you go) |
-| Flat [platform fee](legacy-plans.md#platform-fee) of $99 per month | No | Yes |
+| **Feature** | **Plan Required** |
+| ----------------------- | ------------------- |
+| AI Search | Premium or Ultimate |
+| PDF Export | Premium or Ultimate |
+| Search Insights | Premium or Ultimate |
+| Custom Domains | Premium or Ultimate |
+| Page Ratings/Feedback | Premium or Ultimate |
+| Advanced Customizations | Premium or Ultimate |
+| Unlisted Visibility | Premium or Ultimate |
+| Shared Links | Premium or Ultimate |
+| Authenticated Access | Ultimate |
+| Site Redirects | Premium or Ultimate |
+| Site Sections | Ultimate |
diff --git a/account-management/plans/sponsored-site-plan.md b/account-management/plans/sponsored-site-plan.md
deleted file mode 100644
index 33ec5c66..00000000
--- a/account-management/plans/sponsored-site-plan.md
+++ /dev/null
@@ -1,52 +0,0 @@
----
-description: >-
- Learn more about how you can earn money from your documentation site with our
- Sponsored site plan
----
-
-# Sponsored site plan
-
-{% hint style="info" %}
-This plan is being slowly rolled out to GitBook users. If you don’t have access to publish your site using this plan, hang tight as we continue to roll this plan out to more users.
-{% endhint %}
-
-
-
-The Sponsored site plan lets you access all of GitBook’s best docs site features at no cost while displaying a small, relevant ad in the corner of your documentation site. Each view generates revenue for you, turning your documentation into a source of income.
-
-### Apply for the Sponsored site plan
-
-The Sponsored site plan is designed specifically for sites. View the steps below to learn how to publish your first sponsored site.
-
-{% stepper %}
-{% step %}
-### Create and publish a Sponsored site
-
-Begin by creating a new site from the site wizard and setting up your site with content. When asked to choose a plan, head to the **For open source** section, and choose the Sponsored site plan.
-{% endstep %}
-
-{% step %}
-### Submit your site for ad review
-
-Your site must be [published **publicly**](../../published-documentation/publish-a-docs-site/public-publishing.md) for **seven days** before you can submit it for review.
-
-Head to your site’s settings, and scroll down to the **Ads and sponsorship** section. From here, review the ads checklist to make sure your site meets all the requirements before submitting.
-{% endstep %}
-
-{% step %}
-### Wait for review
-
-After submitting your application, here’s what you can expect:
-
-* **Review process:** Your site will be reviewed, and you can expect an estimated review time of **up to seven days**. Please note that this timeline may be different based on processing delays.
-* **Final status update:** After the review, we’ll update your site’s status. Your site will either be marked as **approved** or **rejected**, depending on the review outcome. If approved, ads will be added to your site and you can start earning money!
-{% endstep %}
-{% endstepper %}
-
-### How it works
-
-Once your site is live, here’s how the Sponsored site plan operates:
-
-* **Earning potential:** Every time someone views your documentation, a small, relevant ad will be displayed in the bottom corner of each page. You earn money from every view, which you can use to support ongoing development efforts.
-* **Ethical advertising:** At GitBook, we prioritize ethical advertising. Ads displayed on your site will never track or retarget your users, ensuring a respectful experience for your audience.
-* **Visibility of content:** Your content remains the focus. Only one small ad will appear on each page, ensuring that your documentation is always front and center.
diff --git a/account-management/sso-and-saml/README.md b/account-management/sso-and-saml/README.md
index 061bffae..e2235e3a 100644
--- a/account-management/sso-and-saml/README.md
+++ b/account-management/sso-and-saml/README.md
@@ -1,19 +1,93 @@
---
-description: Discover how to share your GitBook content via SSO&SAML.
+description: Learn how to share your GitBook content via SSO & SAML.
icon: building-lock
---
# SSO & SAML
-GitBook allows you to invite users with email domains or your chosen identity provider.
+While manually managing your organization members is fine for smaller teams or folks who want tonnes of control, sometimes you just need to open things up in a more automated way. GitBook allows you to configure this in a couple of ways, through a basic email domain SSO, and a more complex SAML integration.
+
+## Single sign-on via email domain
+
+When you create or manage your organisation, you can add a list of email domains that you want to allow to access your GitBook organization. This means that anyone with a verified email address that matches your configured SSO domains will be allowed to join your organization.
+
+You can enable email domain SSO in the ’SSO’ section of your organization settings; enter a comma-separated list of email domains you’d like to allow SSO access for and you’re good to go.
+
+
Set up SSO for your organization.
{% hint style="info" %}
-**Permissions**
+Anyone who joins via an SSO email domain will default to guest access, you can change their role at any time in the members section of your organization settings.
+{% endhint %}
+
+**SAML-based Single Sign-On** (SSO) gives members access to GitBook through an identity provider (IdP) of your choice.
+
+GitBook easily integrates with your existing identity provider (IdP) so you can provide your employees with single sign-on to GitBook using the same credentials and login experience as your other service providers.
+
+By using SSO, your employees will be able to log into GitBook using the familiar identity provider interface, instead of the GitBook login page. The employee’s browser will then forward them to GitBook. The IdP grants access to GitBook when SSO is enabled and GitBook’s own login mechanism is deactivated. In this way, authentication security is shifted to your IdP and coordinated with your other service providers.
+
+## Prerequisites for SSO with GitBook
+
+* Your company’s identity provider (IdP) must support the **SAML 2.0** standard.
+* You must have administrative permission on the IdP.
+* You must be an administrator of the GitBook organization you want to set SAML up on.
+
+## Setup on GitBook
+
+You must be an [organization admin](../member-management/roles.md#admin) to enable SSO for your GitBook organization.
+
+After configuring SSO on your IdP, you will be able to enter metadata. When the setup is successful, administrators will see a confirmation dialog and the URL of the SSO login for end-users will be displayed. **GitBook does not send announcement emails when set up is complete**. It is the responsibility of the administrator to notify company employees (and convey the login URL to them) so they can access GitBook via SSO.
+
+You’ll need the following from your IdP metadata to register a SAML provider:
+
+* A **label** – this can be anything, it’ll be displayed on the login page
+* An **entity ID**
+* A **Single Sign On URL**
+* An **X.509 certificate** – make sure you copy and paste the whole certificate!
+
+## Setup on the IdP
-SSO and SAML can only be set by users with admin rights.
+Most SAML 2.0 compliant identity providers require the same information about the service provider (GitBook, in this case) for set up. These values are specific to your GitBook organization and are available in the **Settings -> SSO** tab of the GitBook organization where you want to enable SSO.
+
+Most of these values can be copied directly into your IdP to complete configuration of SAML.
+
+GitBook requires that the **NameID** contain the user’s email address. Technically we are looking for: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` as the Name-ID format – many providers (such as Google) will allow you set a format such as **EMAIL**.
+
+### Custom Attributes
+
+GitBook will pull the following custom attributes from the SAML assert response and use them when creating the user.
+
+| Field | Description |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| `first_name` | `first_name` and `last_name` fields will be combined to produce the display name for the user in GitBook |
+| `last_name` | `first_name` and `last_name` fields will be combined to produce the display name for the user in GitBook |
+
+## Creating end-user accounts
+
+To add members, create accounts for them in your IdP. The first time a new member logs in to GitBook via the IdP, a GitBook account will be created for them via automatic IdP provisioning. The user will have access to organization resources as an organization member.
+
+{% hint style="danger" %}
+Set-up requires lower case email addresses. Do not use mixed case email addresses.
{% endhint %}
-### **Learn more about:**
+## Removing accounts
+
+Removing a member from the IdP will prevent the user from being able to sign in to the corresponding GitBook account, **but will not remove the account from GitBook**. We advise also removing the account from the GitBook organization.
+
+## Controlling access
+
+Once you have set up SAML SSO, the onus is on the IdP to control who can access your GitBook account.
+
+## Security notice
+
+If you have an existing GitBook account under the same email address as the one we get from Identity Provider and you are not a member of the organization you're trying to sign into, we will not be able to automatically add you to the organization with the SAML configuration due to security reasons. You have two options:
+
+1. Delete your existing GitBook account and then log into your desired organization with SAML. GitBook will then create a new account for you and you will be added to the organization
+2. Or, ask your admin to invite you to the organization:
+
+If your organization does not have "Enforce SSO" enabled, an admin of your organization can invite users through the Members page in your organization's settings.
-
SSO
Add a list of email domains allowed to access your GitBook organization.
+If your organization has enabled "Enforce SSO", an admin will have to use GitBook's `invites` API endpoint to invite users to the organization. A call to this API would look like the following;
+```
+curl --request POST --header "Authorization: Bearer " --url "https://api.gitbook.com/v1/orgs//invites" --header 'Content-Type: application/json' --data-raw '{ "sso": true, "role": "", "emails":[""] }'
+```
diff --git a/account-management/sso-and-saml/saml/README.md b/account-management/sso-and-saml/saml/README.md
deleted file mode 100644
index eca92844..00000000
--- a/account-management/sso-and-saml/saml/README.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# SAML single sign-on
-
-{% hint style="info" %}
-This feature is included in the Pro and Enterprise plans.
-{% endhint %}
-
-**SAML-based Single Sign-On** (SSO) gives members access to GitBook through an identity provider (IdP) of your choice.
-
-GitBook easily integrates with your existing identity provider (IdP) so you can provide your employees with single sign-on to GitBook using the same credentials and login experience as your other service providers.
-
-By using SSO, your employees will be able to log into GitBook using the familiar identity provider interface, instead of the GitBook login page. The employee’s browser will then forward them to GitBook. The IdP grants access to GitBook when SSO is enabled and GitBook’s own login mechanism is deactivated. In this way, authentication security is shifted to your IdP and coordinated with your other service providers.
-
-## Prerequisites for SSO with GitBook
-
-* Your company’s identity provider (IdP) must support the **SAML 2.0** standard.
-* You must have administrative permission on the IdP.
-* You must be an administrator of the GitBook organization you want to set SAML up on.
-
-## Setup on GitBook
-
-You must be an [organization admin](../../member-management/roles.md#admin) to enable SSO for your GitBook organization.
-
-After configuring SSO on your IdP, you will be able to enter metadata. When the setup is successful, administrators will see a confirmation dialog and the URL of the SSO login for end-users will be displayed. **GitBook does not send announcement emails when set up is complete**. It is the responsibility of the administrator to notify company employees (and convey the login URL to them) so they can access GitBook via SSO.
-
-
Register a SAML provider.
-
-You’ll need the following from your IdP metadata to register a SAML provider:
-
-* A **label** – this can be anything, it’ll be displayed on the login page
-* An **entity ID**
-* A **Single Sign On URL**
-* An **X.509 certificate** – make sure you copy and paste the whole certificate!
-
-## Setup on the IdP
-
-Most SAML 2.0 compliant identity providers require the same information about the service provider (GitBook, in this case) for set up. These values are specific to your GitBook organization and are available in the **Settings -> SSO** tab of the GitBook organization where you want to enable SSO.
-
-Most of these values can be copied directly into your IdP to complete configuration of SAML.
-
-GitBook requires that the **NameID** contain the user’s email address. Technically we are looking for: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` as the Name-ID format – many providers (such as Google) will allow you set a format such as **EMAIL**.
-
-### Custom Attributes
-
-GitBook will pull the following custom attributes from the SAML assert response and use them when creating the user.
-
-| Field | Description |
-| ------------ | -------------------------------------------------------------------------------------------------------- |
-| `first_name` | `first_name` and `last_name` fields will be combined to produce the display name for the user in GitBook |
-| `last_name` | `first_name` and `last_name` fields will be combined to produce the display name for the user in GitBook |
-
-## Creating end-user accounts
-
-To add members, create accounts for them in your IdP. The first time a new member logs in to GitBook via the IdP, a GitBook account will be created for them via automatic IdP provisioning. The user will have access to organization resources as an organization member.
-
-{% hint style="danger" %}
-Set-up requires lower case email addresses. Do not use mixed case email addresses.
-{% endhint %}
-
-## Removing accounts
-
-Removing a member from the IdP will prevent the user from being able to sign in to the corresponding GitBook account, **but will not remove the account from GitBook**. We advise also removing the account from the GitBook organization.
-
-## Controlling access
-
-Once you have set up SAML SSO, the onus is on the IdP to control who can access your GitBook account.
-
-## Security notice
-
-If you have an existing GitBook account under the same email address as the one we get from Identity Provider and you are not a member of the organization you're trying to sign into, we will not be able to automatically add you to the organization with the SAML configuration due to security reasons. You have two options:\
-
-
-1. Delete your existing GitBook account and then log into your desired organization with SAML. GitBook will then create a new account for you and you will be added to the organization
-2. Or, ask your admin to invite you to the organization:
-
-If your organization does not have "Enforce SSO" enabled, an admin of your organization can invite users through the Members page in your organization's settings.
-
-If your organization has enabled "Enforce SSO", an admin will have to use GitBook's `invites` API endpoint to invite users to the organization. A call to this API would look like the following;
-
-```
-curl --request POST --header "Authorization: Bearer " --url "https://api.gitbook.com/v1/orgs//invites" --header 'Content-Type: application/json' --data-raw '{ "sso": true, "role": "", "emails":[""] }'
-```
diff --git a/account-management/sso-and-saml/sso-and-saml.md b/account-management/sso-and-saml/sso-and-saml.md
deleted file mode 100644
index 09c61c9d..00000000
--- a/account-management/sso-and-saml/sso-and-saml.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# SSO
-
-While manually managing your organization members is fine for smaller teams or folks who want tonnes of control, sometimes you just need to open things up in a more automated way. GitBook allows you to configure this in a couple of ways, through a basic email domain SOO, and a more complex [SAML integration](saml/).
-
-## Single sign-on via email domain
-
-When you create or manage your organisation, you can add a list of email domains that you want to allow to access your GitBook organization. This means that anyone with a verified email address that matches your configured SSO domains will be allowed to join your organization.
-
-You can enable email domain SSO in the ’SSO’ section of your organization settings; enter a comma-separated list of email domains you’d like to allow SSO access for and you’re good to go.
-
-
Set up SSO for your organization.
-
-{% hint style="info" %}
-Anyone who joins via an SSO email domain will default to guest access, you can change their role at any time in the members section of your organization settings.
-{% endhint %}
diff --git a/account-management/sso-and-saml/saml/sso-members-vs-non-sso.md b/account-management/sso-and-saml/sso-members-vs-non-sso.md
similarity index 93%
rename from account-management/sso-and-saml/saml/sso-members-vs-non-sso.md
rename to account-management/sso-and-saml/sso-members-vs-non-sso.md
index dd238703..112d322d 100644
--- a/account-management/sso-and-saml/saml/sso-members-vs-non-sso.md
+++ b/account-management/sso-and-saml/sso-members-vs-non-sso.md
@@ -23,7 +23,7 @@ When a user sees their SSO login not succeeding with the message "Log in with yo
or
* The user can log in to their account using the credentials initially used to create the account. For example, by clicking on "Continue with email" to receive an email sign-in link.
-* :information\_source: SSO login will not be automatically enabled for this user, and an organization administrator has to enable it explicitly from the admin dashboard.
+* SSO login will not be automatically enabled for this user, and an organization administrator has to enable it explicitly from the admin dashboard.
#### If the user account is not yet a member of the organization:
diff --git a/api-references/extensions-reference.md b/api-references/extensions-reference.md
new file mode 100644
index 00000000..8f88cbb3
--- /dev/null
+++ b/api-references/extensions-reference.md
@@ -0,0 +1,281 @@
+---
+description: The complete reference of OpenAPI extensions supported by GitBook.
+icon: code
+---
+
+# Extensions reference
+
+You can enhance your OpenAPI specification using extensions—custom fields that start with the `x-` prefix. These extensions let you add extra information and tailor your API documentation to suit different needs.
+
+GitBook allows you to adjust how your API looks and works on your published site through a range of different extensions you can add to your OpenAPI spec.
+
+Head to our [guides section](guides/) to learn more about using OpenAPI extensions to configure your documentation.
+
+
+
+x-page-title | x-displayName
+
+Change the display name of a tag used in the navigation and page title.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags:
+ - name: users
+ x-page-title: Users
+```
+{% endcode %}
+
+
+
+
+
+x-page-description
+
+Add a description to the page.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags:
+ - name: "users"
+ x-page-title: "Users"
+ x-page-description: "Manage user accounts and profiles."
+```
+{% endcode %}
+
+
+
+
+
+x-page-icon
+
+Add a Font Awesome icon to the page. See available icons [here](https://fontawesome.com/search).
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags:
+ - name: "users"
+ x-page-title: "Users"
+ x-page-description: "Manage user accounts and profiles."
+ x-page-icon: "user"
+```
+{% endcode %}
+
+
+
+
+
+x-parent | parent
+
+Add hierarchy to tags to organize your pages in GitBook.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags:
+ - name: organization
+ - name: admin
+ x-parent: organization
+ - name: user
+ x-parent: organization
+```
+{% endcode %}
+
+
+
+
+
+x-hideTryItPanel
+
+Show or hide the “Test it” button for an OpenAPI block.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ responses: [...]
+ parameters: [...]
+ x-hideTryItPanel: true
+```
+{% endcode %}
+
+
+
+
+
+x-codeSamples
+
+Show, hide, or include custom code samples for an OpenAPI block.
+
+#### Fields
+
+
Field Name
Type
Description
lang
string
Code sample language. Value should be one of the following list
label
string
Code sample label, for example Node or Python2.7, optional, lang is used by default
source
string
Code sample source code
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ responses: [...]
+ parameters: [...]
+ x-codeSamples:
+ - lang: 'cURL'
+ label: 'CLI'
+ source: |
+ curl -L \
+ -H 'Authorization: Bearer ' \
+ 'https://api.gitbook.com/v1/user'
+```
+{% endcode %}
+
+
+
+
+
+x-enumDescriptions
+
+Add an individual description for each of the `enum` values in your schema.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+components:
+ schemas:
+ project_status:
+ type: string
+ enum:
+ - LIVE
+ - PENDING
+ - REJECTED
+ x-enumDescriptions:
+ LIVE: The project is live.
+ PENDING: The project is pending approval.
+ REJECTED: The project was rejected.
+```
+{% endcode %}
+
+
+
+
+
+x-internal | x-gitbook-ignore
+
+Hide an endpoint from your API reference.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ responses: [...]
+ parameters: [...]
+ x-internal: true
+```
+{% endcode %}
+
+
+
+
+
+x-stability
+
+Mark endpoints that are unstable or in progress.
+
+Supported values: `experimental`, `alpha`, `beta`.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ x-stability: experimental
+```
+{% endcode %}
+
+
+
+
+
+deprecated
+
+Mark whether an endpoint is deprecated or not. Deprecated endpoints will give deprecation warnings in your published site.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ responses: [...]
+ parameters: [...]
+ deprecated: true
+```
+{% endcode %}
+
+
+
+
+
+x-deprecated-sunset
+
+Add a sunset date to a deprecated operation.
+
+Supported values: **ISO 8601** format (YYYY-MM-DD)
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ responses: [...]
+ parameters: [...]
+ deprecated: true
+ x-deprecated-sunset: 2030-12-05
+```
+{% endcode %}
+
+
+
diff --git a/api-references/guides/README.md b/api-references/guides/README.md
new file mode 100644
index 00000000..508bfa5c
--- /dev/null
+++ b/api-references/guides/README.md
@@ -0,0 +1,6 @@
+---
+icon: book-open
+---
+
+# Guides
+
diff --git a/api-references/guides/adding-custom-code-samples.md b/api-references/guides/adding-custom-code-samples.md
new file mode 100644
index 00000000..bc9fb888
--- /dev/null
+++ b/api-references/guides/adding-custom-code-samples.md
@@ -0,0 +1,42 @@
+---
+description: >-
+ Learn how to configure custom code samples to display alongside your API
+ endpoints.
+---
+
+# Adding custom code samples
+
+GitBook can automatically generate generic code examples for each API operation. If you’d prefer to showcase custom or more detailed snippets, add `x-codeSamples` to your OpenAPI definition. This way, you control how your endpoints are demonstrated and can offer language or SDK-specific examples.
+
+{% code title="openapi.yaml" %}
+```yaml
+paths:
+ /users:
+ get:
+ summary: Retrieve users
+ x-codeSamples:
+ - lang: JavaScript
+ label: Node SDK
+ source: |
+ import { createAPIClient } from 'my-api-sdk';
+
+ const client = createAPIClient({ apiKey: 'my-api-key' });
+ client.users.list().then(users => {
+ console.log(users);
+ });
+ - lang: Java
+ label: Java SDK
+ source: |
+ MyApiClient client = new MyApiClient("my-api-key");
+ List users = client.getUsers();
+ System.out.println(users);
+```
+{% endcode %}
+
+**Key Points**
+
+* `x-codeSamples` is an array of code sample objects.
+* Each object defines:
+ * `lang`: The language of the code (e.g., JavaScript, Java).
+ * `label`: A short label for the code block.
+ * `source`: The actual code snippet.
diff --git a/api-references/guides/configuring-the-test-it-button.md b/api-references/guides/configuring-the-test-it-button.md
new file mode 100644
index 00000000..e4f067c4
--- /dev/null
+++ b/api-references/guides/configuring-the-test-it-button.md
@@ -0,0 +1,157 @@
+# Configuring the “Test it” button
+
+You can configure the "Test It" button and accompanying window in GitBook using several OpenAPI extensions. These extensions can help improve and configure the testing suite for users.
+
+### Hiding the “Test it” button
+
+You can hide the “Test it” button from your endpoints by adding the `x-hideTryItPanel` to an endpoint, or at the root of your OpenAPI spec.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+tags: [...]
+paths:
+ /example:
+ get:
+ summary: Example summary
+ description: Example description
+ operationId: examplePath
+ responses: [...]
+ parameters: [...]
+ x-hideTryItPanel: true
+```
+{% endcode %}
+
+### Enable authentication in the testing window
+
+The request runner can only present and apply auth if your spec declares it. Define schemes under `components.securitySchemes`, then attach them either globally via `security` (applies to all operations) or per-operation (overrides global).
+
+#### Declare your auth scheme
+
+Below are common patterns. Use straight quotes in YAML.
+
+{% tabs %}
+{% tab title="HTTP Bearer (e.g., JWT)" %}
+```yaml
+openapi: '3.0.3'
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+```
+{% endtab %}
+
+{% tab title="API Key in header" %}
+```yaml
+openapi: '3.0.3'
+components:
+ securitySchemes:
+ apiKeyAuth:
+ type: apiKey
+ in: header
+ name: X-API-Key
+```
+{% endtab %}
+
+{% tab title="OAuth2 (authorizationCode)" %}
+```yaml
+openapi: '3.0.3'
+components:
+ securitySchemes:
+ oauth2:
+ type: oauth2
+ flows:
+ authorizationCode:
+ authorizationUrl: 'https://auth.example.com/oauth/authorize'
+ tokenUrl: 'https://auth.example.com/oauth/token'
+ scopes:
+ read:items: 'Read items'
+ write:items: 'Write items'
+```
+{% endtab %}
+{% endtabs %}
+
+#### Apply schemes globally or per operation
+
+{% tabs %}
+{% tab title="Gloabl" %}
+```yaml
+openapi: '3.0.3'
+security:
+ - bearerAuth: []
+paths: ...
+```
+{% endtab %}
+
+{% tab title="Per-operation" %}
+```yaml
+paths:
+ /reports:
+ get:
+ summary: Get reports
+ security:
+ - apiKeyAuth: []
+ responses:
+ '200':
+ description: OK
+```
+{% endtab %}
+{% endtabs %}
+
+### Control the endpoint URL with `servers`
+
+The request runner targets the URL(s) you define in the `servers` array. Declare one or more servers; you can also parameterize them with variables.
+
+{% tabs %}
+{% tab title="Single server" %}
+```yaml
+openapi: '3.0.3'
+servers:
+ - url: https://instance.api.region.example.cloud
+```
+{% endtab %}
+
+{% tab title="Multiple servers" %}
+```yaml
+servers:
+ - url: https://api.example.com
+ description: Production
+ - url: https://staging-api.example.com
+ description: Staging
+```
+{% endtab %}
+
+{% tab title="Server variables" %}
+```yaml
+servers:
+ - url: https://{instance}.api.{region}.example.cloud
+ variables:
+ instance:
+ default: acme
+ description: Your tenant or instance slug
+ region:
+ default: eu
+ enum:
+ - eu
+ - us
+ - ap
+ description: Regional deployment
+```
+{% endtab %}
+
+{% tab title="Per-operation servers" %}
+
+{% endtab %}
+{% endtabs %}
diff --git a/api-references/guides/describing-enums.md b/api-references/guides/describing-enums.md
new file mode 100644
index 00000000..04a6c0de
--- /dev/null
+++ b/api-references/guides/describing-enums.md
@@ -0,0 +1,27 @@
+---
+description: Learn how to add descriptions to enums.
+---
+
+# Describing enums
+
+When an API operation includes an enum, you can add `x-enumDescriptions` to provide more context about each option. GitBook will display the enum values and their descriptions in a table next to the operation.
+
+{% code title="openapi.yaml" %}
+```yaml
+openapi: '3.0'
+info: ...
+components:
+ schemas:
+ project_status:
+ type: string
+ enum:
+ - LIVE
+ - PENDING
+ - REJECTED
+ x-enumDescriptions:
+ LIVE: The project is live.
+ PENDING: The project is pending approval.
+ REJECTED: The project was rejected.
+```
+{% endcode %}
+
diff --git a/api-references/guides/managing-api-operations.md b/api-references/guides/managing-api-operations.md
new file mode 100644
index 00000000..12b6b908
--- /dev/null
+++ b/api-references/guides/managing-api-operations.md
@@ -0,0 +1,65 @@
+---
+description: >-
+ Learn how to mark an OpenAPI API operation as experimental, deprecated or hide
+ it from your documentation.
+---
+
+# Managing API operations
+
+It’s common to have operations that are not fully stable yet or that need to be phased out. GitBook supports several OpenAPI extensions to help you manage these scenarios.
+
+### Marking operation as experimental, alpha, or beta
+
+Use `x-stability` to communicate that an endpoint is unstable or in progress. It helps users avoid non-production-ready endpoints. Supported values: `experimental`, `alpha`, `beta`.
+
+
+
+### Hiding an operation from the API reference
+
+To hide an operation from your API reference, add `x-internal: true` or `x-gitbook-ignore: true` attribute.
+
+
diff --git a/api-references/guides/structuring-your-api-reference.md b/api-references/guides/structuring-your-api-reference.md
new file mode 100644
index 00000000..10794aab
--- /dev/null
+++ b/api-references/guides/structuring-your-api-reference.md
@@ -0,0 +1,118 @@
+---
+description: >-
+ Learn how to structure your API reference across multiple pages with icons and
+ descriptions.
+---
+
+# Structuring your API reference
+
+GitBook does more than just render your OpenAPI spec. It lets you customize your API reference for better clarity, navigation, and branding.
+
+### Split operations across multiple pages
+
+To keep your documentation organized, GitBook can split your API operations into separate pages. Each page is generated from a tag in your OpenAPI spec. To group operations into a page, assign the same tag to each operation:
+
+
paths:
+ /pet:
+ put:
+ tags:
+ - pet
+ summary: Update an existing pet.
+ description: Update an existing pet by Id.
+ operationId: updatePet
+
+
+### Reorder pages in your table of contents
+
+The order of pages in GitBook matches the order of tags in your OpenAPI tags array:
+
+
tags:
+ - name: pet
+ - name: store
+ - name: user
+
+
+### Nest pages into groups
+
+To build multi-level navigation, use `x-parent` (or `parent`) in tags to define hierarchy:
+
+
tags:
+ - name: everything
+ - name: pet
+ x-parent: everything
+ - name: store
+ x-parent: everything
+
+
+The above example will create a table of contents that looks like:
+
+```
+Everything
+├── Pet
+└── Store
+```
+
+If a page has no description, GitBook will automatically show a card-based layout for its sub-pages.
+
+### Customize page titles, icons, and descriptions
+
+You can enhance pages with titles, icons, and descriptions using custom extensions in the tags section. All [Font Awesome icons](https://fontawesome.com/search) are supported via `x-page-icon`.
+
+{% code title="openapi.yaml" %}
+```yaml
+tags:
+ - name: pet
+ # Page title displayed in table of contents and page
+ -x-page-title: Pet
+ # Icon shown in table of contents and next to page title
+ -x-page-icon: dog
+ # Description shown just above the title
+ -x-page-description: Pets are amazing!
+ # Content of the page
+ description: Everything about your Pets
+```
+{% endcode %}
+
+### Build rich descriptions with GitBook Blocks
+
+Tag description fields support GitBook markdown, including [advanced blocks](../../creating-content/blocks/) like tabs:
+
+{% code title="openapi.yaml" %}
+```yaml
+---
+tags:
+ - name: pet
+ description: |
+ Here is the detail of pets.
+
+ {% tabs %}
+ {% tab title="Dog" %}
+ Here are the dogs
+ {% endtab %}
+
+ {% tab title="Cat" %}
+ Here are the cats
+ {% endtab %}
+
+ {% tab title="Rabbit" %}
+ Here are the rabbits
+ {% endtab %}
+ {% endtabs %}
+```
+{% endcode %}
+
+### Highlight schemas
+
+You can highlight a schema in a GitBook description by using GitBook markdown. Here is an example that highlights the “Pet” schema from the “petstore” specification:
+
+{% code title="openapi.yaml" %}
+```yaml
+---
+tags:
+ - name: pet
+ description: |
+ {% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
+ The Pet object
+ {% endopenapi-schemas %}
+```
+{% endcode %}
diff --git a/api-references/guides/support-for-ci-cd-with-api-blocks.md b/api-references/guides/support-for-ci-cd-with-api-blocks.md
new file mode 100644
index 00000000..5838bf8f
--- /dev/null
+++ b/api-references/guides/support-for-ci-cd-with-api-blocks.md
@@ -0,0 +1,85 @@
+---
+description: Learn how to automate the update of your OpenAPI specification in GitBook.
+---
+
+# Integrating with CI/CD
+
+GitBook can work with any CI/CD pipeline you already have for managing your OpenAPI specification. By using the GitBook CLI, you can automate updates to your API reference.
+
+### Upload a specification file
+
+If your OpenAPI spec is generated during your CI process, you can upload it directly from your build environment:
+
+```bash
+# Set your GitBook API token as an environment variable
+export GITBOOK_TOKEN=
+
+gitbook openapi publish \
+ --spec spec_name \
+ --organization organization_id \
+ example.openapi.yaml
+```
+
+### Set a new source URL or trigger a refresh
+
+If your OpenAPI specification is hosted at a URL, GitBook automatically checks for updates. To force an update (for example, after a release), run:
+
+```bash
+# Set your GitBook API token as an environment variable
+export GITBOOK_TOKEN=
+
+gitbook openapi publish \
+ --spec spec_name \
+ --organization organization_id \
+ https://api.example.com/openapi.yaml
+```
+
+### Update your spec with GitHub Actions
+
+If you’re setting up a workflow to publish your OpenAPI spec, complete these steps in your repository:
+
+1. In your repo, go to “Settings → Secrets and variables → Actions”.
+2. Add a secret: `GITBOOK_TOKEN` (your GitBook API token).
+3. Add variables (or hardcode them in the workflow):
+ * `GITBOOK_SPEC_NAME` → your spec’s name in GitBook
+ * `GITBOOK_ORGANIZATION_ID` → your GitBook organization ID
+4. Save the workflow file as `.github/workflows/gitbook-openapi-publish.yml`.
+5. Push changes to “main” (or run the workflow manually).
+
+You can then use this action to update your spec:
+
+{% code title=".github/workflows/gitbook-openapi-publish.yml" %}
+```yaml
+name: Publish OpenAPI to GitBook
+
+on:
+ push:
+ branches: [ "main" ]
+ paths:
+ - "**/*.yaml"
+ - "**/*.yml"
+ - "**/*.json"
+ workflow_dispatch:
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+ env:
+ # Required secret
+ GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
+ # Prefer repo/org variables; fallback to inline strings if you like
+ GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
+ GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Publish spec file to GitBook
+ run: |
+ npx -y @gitbook/cli@latest openapi publish \
+ --spec "$GITBOOK_SPEC_NAME" \
+ --organization "$GITBOOK_ORGANIZATION_ID" \
+
+```
+{% endcode %}
diff --git a/api-references/openapi/README.md b/api-references/openapi/README.md
new file mode 100644
index 00000000..926e859c
--- /dev/null
+++ b/api-references/openapi/README.md
@@ -0,0 +1,26 @@
+---
+description: >-
+ Add an OpenAPI spec to a page and let your users test endpoints right on the
+ page with interactive blocks.
+icon: brackets-curly
+---
+
+# OpenAPI
+
+Manually writing REST API documentation can be a time-consuming process. Fortunately, GitBook streamlines this task by allowing you to import OpenAPI documents, which detail your API’s structure and functionality.
+
+The OpenAPI Specification (OAS) is a framework that developers use to document REST APIs. Written in JSON or YAML, it outlines all your endpoints, parameters, schemas, and authentication schemes.
+
+Once imported into GitBook, these documents are transformed into interactive and testable API blocks that visually represent your API methods—whether the specification is provided as a file or loaded from a URL.
+
+GitBook supports [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) or [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) compliant files.
+
+{% openapi src="https://petstore3.swagger.io/api/v3/openapi.json" path="/pet" method="post" %}
+[https://petstore3.swagger.io/api/v3/openapi.json](https://petstore3.swagger.io/api/v3/openapi.json)
+{% endopenapi %}
+
+### Test it (powered by Scalar)
+
+GitBook's OpenAPI block also supports a "test it" functionality, which allows your users to test your API methods with data and parameters filled in from the editor.
+
+Powered by [Scalar](https://scalar.com/), you won't need to leave the docs in order to see your API methods in action. See and example of this above.
diff --git a/api-references/openapi/add-an-openapi-specification.md b/api-references/openapi/add-an-openapi-specification.md
new file mode 100644
index 00000000..c0112fcf
--- /dev/null
+++ b/api-references/openapi/add-an-openapi-specification.md
@@ -0,0 +1,50 @@
+---
+description: >-
+ Learn how to add and update an OpenAPI specification in GitBook application or
+ from CLI.
+---
+
+# Add an OpenAPI specification
+
+If you have an OpenAPI spec, you can add it to your organization by uploading the file directly, linking to a hosted URL, or using the [GitBook CLI](https://gitbook.com/docs/developers/integrations/reference).
+
+
+
+### How to add a specification
+
+1. Open the **OpenAPI** section in the sidebar
+2. Click on **Add specification**
+3. Give your specification a name. This helps identify it, especially if you manage multiple specs
+4. Choose one of the following:
+ * Upload a file (e.g. _openapi.yaml_)
+ * Enter a URL to a hosted spec
+ * Use the CLI to publish the spec
+
+
Add an OpenAPI specification modal.
+
+### Update your specification
+
+You can update your OpenAPI specification at any time using the GitBook UI or the CLI, regardless of how it was initially added.
+
+#### In GitBook Application
+
+In the OpenAPI panel:
+
+* If your spec is linked to a URL:
+ * GitBook checks for updates automatically **every 6 hours**.
+ * To fetch updates immediately, click **Check for updates**.
+* If your spec was uploaded as a file:
+ * Click **Update** to upload a new version.
+* You can switch from a File to a URL source by clicking on **Edit** in the breadcrumb actions menu.
+
+#### Using the CLI
+
+Use the same command to update your specification:
+
+```bash
+gitbook openapi publish --spec api-spec-name --organization organization_id
+```
+
+You can also use the CLI to **Check for updates** by running the publish command on the same URL.
+
+Read our [support-for-ci-cd-with-api-blocks.md](../guides/support-for-ci-cd-with-api-blocks.md "mention") guide to learn how to automate the update of your specification.
diff --git a/api-references/openapi/insert-api-reference-in-your-docs.md b/api-references/openapi/insert-api-reference-in-your-docs.md
new file mode 100644
index 00000000..6dc359a2
--- /dev/null
+++ b/api-references/openapi/insert-api-reference-in-your-docs.md
@@ -0,0 +1,67 @@
+---
+description: >-
+ Insert complete API reference from your OpenAPI spec or pick individual
+ operation or schemas.
+---
+
+# Insert API reference in your docs
+
+GitBook allows you to automatically generate pages related to the endpoints you have in your OpenAPI spec. These pages will contain OpenAPI operation blocks, allowing you and your visitors to test your endpoints and explore them further based on the information found in the spec.
+
+{% hint style="success" %}
+Endpoints added from your spec will continue to be updated anytime your spec is updated. See the [Update your specification](add-an-openapi-specification.md#update-your-specification) section for more info.
+{% endhint %}
+
+### Automatically create OpenAPI pages from your spec
+
+After you’ve [added your OpenAPI spec](add-an-openapi-specification.md), you can generate endpoint pages by inserting an **OpenAPI Reference** in the table of contents of a Space.
+
+
Insert API References in the table of contents of a Space.
+
+{% stepper %}
+{% step %}
+#### Generate pages from OpenAPI
+
+In the space you’d like to generate endpoint pages, click the **Add new...** button from the bottom of your space’s [table of contents](../../resources/gitbook-ui.md#table-of-contents).
+
+From here, click **OpenAPI Reference**.
+{% endstep %}
+
+{% step %}
+#### Choose your OpenAPI spec
+
+Choose your previously uploaded OpenAPI spec, and click **Insert** to automatically add your endpoints to your space. You can optionally choose to add a models page referencing all your OpenAPI schemas.
+{% endstep %}
+
+{% step %}
+#### Manage your API operations
+
+GitBook will automatically generate pages based on your OpenAPI spec and the tags set inside it’s definition.
+
+Head to [structuring-your-api-reference.md](../guides/structuring-your-api-reference.md "mention") to learn more about organizing your operations through your OpenAPI spec.
+{% endstep %}
+{% endstepper %}
+
+### Add an individual OpenAPI block
+
+Alternatively, you can add OpenAPI operations or schemas from your spec individually to pages throughout your docs.
+
+{% stepper %}
+{% step %}
+#### Add a new OpenAPI block
+
+Open the block selector by pressing **/**, and search for OpenAPI.
+{% endstep %}
+
+{% step %}
+#### Choose your OpenAPI spec
+
+Choose your previously uploaded OpenAPI spec, and click **Continue** to choose your the endpoints you’d like to use.
+{% endstep %}
+
+{% step %}
+#### Choose the operations or schemas you’d like to insert
+
+Pick the operations and the schemas you want to insert in your docs and click **Insert**.
+{% endstep %}
+{% endstepper %}
diff --git a/building-technical-product-documentation.md b/building-technical-product-documentation.md
deleted file mode 100644
index 3f3ad3b8..00000000
--- a/building-technical-product-documentation.md
+++ /dev/null
@@ -1,99 +0,0 @@
----
-description: Use GitBook to create technical product documentation
----
-
-# Building technical product documentation
-
-Documentation is a vital part of any product, and teams that nail theirs from the start get ahead of the competition earlier on. Engaging product documentation adds so much value; it increases your user’s confidence in the product, improves the user experience, and increases user satisfaction.
-
-Often, writers of product documentation face challenges related to ease of contribution, updating and maintaining information, and the look and feel of the docs. This can result in having to compromise on at least one of those aspects — but not with GitBook!
-
-GitBook allows you to make writing beautiful documentation part of your everyday workflow.
-
-## Key benefits and features of GitBook
-
-- [**Import or create your content**](building-technical-product-documentation.md#import-or-create-your-content)\
- Get started in a matter of minutes with our intuitive editor.
-- [**Make use of content blocks**](building-technical-product-documentation.md#make-use-of-content-blocks)
-
- Create easy to read content with blocks designed for technical authors and readers.
-
-- [**Collaborate with your team**](building-technical-product-documentation.md#collaborate-with-your-team)
-
- Review your content in change requests while maintaining full control of each version.
-
-- [**Match your existing Git workflow**](building-technical-product-documentation.md#match-your-existing-git-workflow)\
- Bridge the gap between collaborators who write directly in the GitBook editor, and those who prefer to write in Markdown in a GitHub or GitLab repository.
-- [**Customize your documentation**](building-technical-product-documentation.md#customize-your-documentation)\
- Create beautiful docs that match _your_ brand by uploading your logo, setting a primary color, choosing a font, and more.
-- [**Integrate existing tools within your docs**](building-technical-product-documentation.md#integrate-existing-tools-within-your-docs)\
- Include live code samples directly in your doc with RunKit, create graphs and diagrams with Markdown.
-- [**Publish your documentation**](building-technical-product-documentation.md#publish-your-documentation)
-
- Choose from a number of visibility settings, plus you can publish on your own custom domain.
-
-## Import or create your content
-
-GitBook allows you to easily start creating and editing your content. In cases where you already have content written elsewhere, you can [import](broken-reference) it. We support importing from files or websites that are in markdown, HTML or Microsoft word formats, as well as importing from a number of other services.
-
-{% content-ref url="../content-creation/import.md" %}
-[import.md](../content-creation/import.md)
-{% endcontent-ref %}
-
-Alternatively, if you are just kicking off your documentation journey you can easily start writing by designing your [content structure](../content-creation/content-structure/) and inviting other [collaborators](../collaboration/collaboration/) to work with you.
-
-## Make use of content blocks
-
-In addition to standard text, image and list blocks, GitBook allows you to directly include more technical content. Find out more about:
-
-- [Code blocks](../content-creation/blocks/code-block.md)
-- [API blocks](../content-creation/blocks/api-method.md)
-- [More block types](../content-creation/blocks/)
-
-## Collaborate with your team
-
-Once your initial content exists, it’s important to design a contribution workflow that will ensure your documentation remains up-to-date. You can manage the access of each contributor or team of contributors through [permissions and inheritance](../account-management/member-management/permissions-and-inheritance.md), allowing for a review process before merging your content into the main branch.
-
-Each change request is tracked and logged in the [activity tab](../content-creation/activity-history.md), which gives you an overview of the work that has been happening in the space. If you ever need to view or roll back to an older version of the content, you can do that from the [change history](../content-creation/activity-history.md#see-the-activity-of-a-specific-draft) section.
-
-## Match your existing Git workflow
-
-A huge benefit of GitBook is the ability to bridge the gap between contributors who prefer to collaborate in Markdown or write documentation directly in their Git repository and those who may not know Markdown or simply prefer the expanded editing capabilities.
-
-Thanks to our [bi-directional sync](../integrations/git-sync/bi-directional-git-integration.md), documentation is continuously updated regardless of whether it is edited in your Git repository or in GitBook, removing any potential friction or silos in your team.
-
-{% content-ref url="../integrations/git-sync/" %}
-[git-sync](../integrations/git-sync/)
-{% endcontent-ref %}
-
-## Customize your documentation
-
-GitBook makes it easy to align your documentation with your branding. Change the logo, font, primary colour, header and footer links, light or dark mode, and more in our interactive [customizer](../publishing/customization/space-customization.md).
-
-Additionally, each page can make use of one of three [layouts](../publishing/share/page-layouts.md): docs page, editorial post, and landing page. Combining landing pages with docs pages can help with structuring your technical product documentation in a way that helps users find what they’re looking for, faster.
-
-## Integrate existing tools within your docs
-
-We’ve made it easier for your documentation to integrate closely with other tools you use for support, tracking or collaboration allowing you to build one smooth workflow.
-
-Our [RunKit](https://github.com/GitbookIO/integrations) integration allows your users to run sample code directly from your documentation, embedding interactive JavaScript playgrounds connected to a complete Node environment right in your browser.
-
-Our [Mermaid](https://github.com/GitbookIO/integrations) integration allows you to create diagrams and visualizations using text and code. With the integration enabled you can insert the Mermaid block into any page. You can edit the code content and preview how it looks using the live editor.
-
-{% hint style="info" %}
-When using [Git Sync](../integrations/git-sync/), all code blocks with the mermaid syntax will be replaced by diagram. All diagrams inserted from the editor will be formatted as such code blocks in Markdown.
-{% endhint %}
-
-We offer a number of [other integrations](https://github.com/GitbookIO/integrations), too, and have plans to make it easier to extend GitBook with additional integrations in the future. 🤩
-
-## Publish your documentation
-
-When your documentation is ready, publishing it is a breeze! Choose from [a number of options](../publishing/share/space-publishing.md), deciding based on who should have access to the published content.
-
-For complete control, we offer [visitor authentication](../publishing/visitor-authentication.md). This feature lets _your_ server-side code handle who has access to the content.
-
-As a finishing touch, [set a custom domain](../publishing/custom-domain/) so that your visitors can use a subdomain of your choice to access the published documentation. If your website is available at `example.com`, you might choose to set a custom domain of `docs.example.com` for your documentation.
-
-## Start creating your product documentation today
-
-Creating _good_ product documentation can be hard — but GitBook makes it easier! [Sign up](https://app.gitbook.com/join) or [log in](https://app.gitbook.com/) to start trying out these features right away.
diff --git a/collaboration/ai-change-requests.md b/collaboration/ai-change-requests.md
new file mode 100644
index 00000000..9fe576cf
--- /dev/null
+++ b/collaboration/ai-change-requests.md
@@ -0,0 +1,48 @@
+---
+hidden: true
+icon: sparkles
+---
+
+# AI change requests
+
+### Overview
+
+The **AI Change Requests** feature brings the capabilities of GitBook AI to one of the core functionalities of GitBook: Change Requests. This feature streamlines the process of proposing, planning, and implementing changes to your GitBook content by leveraging AI assistance.
+
+With AI Change Requests, you can:
+
+* **Start a new Change Request**: Describe the modifications you want to make, and GitBook AI will draft a plan for review.
+* **Refine and approve the plan**: Review and adjust the AI-generated proposal as needed.
+* **Execute the changes**: Once finalized, GitBook AI will apply the changes directly to your content.
+
+### How It Works
+
+1. **Initiate a Change Request**
+ * Open GitBook and navigate to the Change Requests section.
+ * Start a new Change Request and describe the desired changes. Examples of requests include:
+ * "Find and replace any instances of \[feature name] with \[updated feature name]."
+ * "Correct typos on the Welcome page."
+ * "Reformat the \[product feature] page into three sections: Overview, Installation, and FAQ."
+ * "Add a new page for \[product feature] and document it based on this description: \[product description]."
+2. **Review and Tweak the AI-Generated Plan**
+ * GitBook AI will draft a proposed plan based on your description.
+ * You can review, edit, and refine the draft to ensure it aligns with your vision.
+3. **Execute the Plan**
+ * Approve the final plan to allow GitBook AI to apply the requested changes directly to your project.
+
+### Example Use Cases
+
+* **Content Updates**: Quickly update outdated terminology or features across multiple pages.
+* **Error Correction**: Automatically detect and fix typos or grammatical errors in your documentation.
+* **Page Reorganization**: Restructure content into clear and logical sections.
+* **New Content Creation**: Generate new pages or sections based on high-level descriptions.
+
+### Current Limitations
+
+While the AI Change Requests feature is still in Alpha, there are some known limitations:
+
+* **GitBook-specific blocks**: Updates to these blocks are not yet supported.
+
+### Feedback and Support
+
+As this feature is in its early stages, we welcome your feedback to improve its functionality. Please share your experiences and suggestions with the GitBook team to help us refine AI Change Requests.
diff --git a/collaboration/change-requests.md b/collaboration/change-requests.md
index bf781f19..a0039535 100644
--- a/collaboration/change-requests.md
+++ b/collaboration/change-requests.md
@@ -1,6 +1,6 @@
---
+description: Collaborate on content edits through change requests
icon: code-branch
-description: Control your content edits through change requests.
---
# Change requests
@@ -9,40 +9,26 @@ A change request is a copy of your main content. It comes from the simple concep
In a change request, you can edit, update and delete elements of your content, request reviews on your changes, then merge them back into your main version to apply all the changes you made.
-{% hint style="info" %}
-**Note:** You’ll need to open a change request to edit any content in any [published](../published-documentation/overview.md) space, any space that’s [synced with GitHub or GitLab](../integrations/git-sync/), or any space with [locked live edits](../content-editor/editing-content/live-edits.md).
-{% endhint %}
-
-### Product Demo
-
-{% embed url="https://www.youtube.com/watch?v=qcK2xEJLXRU" %}
+
Edit your content through change requests.
### Creating a change request
-Inside a space where live edits are disabled, click the **Edit in change request** button in the space header to start a new change request.
-
-
You can start a new change request by clicking the Edit button in the top-right of the window, which only appears if live edits are locked.
+Inside a space where live edits are disabled, click the **Edit** button in the [space header](../resources/gitbook-ui.md#space-header) to start a new change request.
This will open a new change request, where you can edit or delete content as needed. Your changes are saved automatically, and other people can join you in a change request to collaborate in real-time.
Once you’re happy with your changes, you can use the button in the header bar to **Request a review** of your change request, or **Merge** it directly into the main branch.
-{% hint style="info" %}
-Any member with an [editor](../account-management/member-management/roles.md#editor) role can create and submit a change request, but only members with a [reviewer](../account-management/member-management/roles.md#reviewer) role or above can merge it.
-{% endhint %}
-
### Preview a change request
-You can preview the changes you've made in a change request through the preview button in the upper right corner. This will open up a window with your docs and the proposed changes in a staging environment, so you and your team can see your changes in the entire context of your published documentation.
+You can preview the changes you've made in a change request through the preview button in the [space header](../resources/gitbook-ui.md#space-header). This will switch you to a view with your docs and the proposed changes in a preview window, so you can see your changes in the entire context of your published documentation.
-{% hint style="warning" %}
-If your content is published using share links or visitor authentication, the preview function won't appear.
+{% hint style="info" %}
+You can only preview change requests for spaces added to a [published docs site](../publishing-documentation/publish-a-docs-site/).
{% endhint %}
-
Preview a Change Request
-
-{% hint style="info" %}
-**Note**: You can only preview change requests for spaces added to a [published docs site](../published-documentation/publish-a-docs-site/).
+{% hint style="warning" %}
+If your content is published using share links or authenticated access, the preview function won't appear.
{% endhint %}
### Request a review on a change request
@@ -51,69 +37,87 @@ Request a review on your change request when you want to ask members of your tea
You can add a description to your change request to give your reviewers some context, and tag specific people that you want to check your work.
-When you click **Request review**, the change request’s status will change to **In review**, and anyone you tagged in your review request will get a notification.
+When you click **Request a review**, the change request’s status will change to **In review**, and anyone you tagged in your review request will get a notification.
+
+If your changes don’t require a review, you can merge your changes into the main version directly instead.
{% hint style="info" %}
-**Note:** If you don’t tag anyone in your review request, everyone with reviewer permissions or higher will get a notification about your request.
+If you don’t tag anyone in your review request, everyone with reviewer permissions or higher will get a notification about your request.
{% endhint %}
-
When you request a review, you can add a description to give people more context, and tag specific reviewers.
+### Reviewing a change request
-If your changes don’t require a review, you can merge your changes into the main version directly instead.
+If you get a request to review a change request, you'll be able to edit the content and leave feedback to make sure it's in good shape before it’s merged to the main version. You can either request changes if you think it still needs work, or approve the change request, to signal it's ready to merge.
-### Merging a change request
+Most reviews will take place in the change request’s [comments](comments.md), where collaborators can share feedback and have discussions about specific content blocks, or the change request as a whole.
-Merging a change request will add the change request’s changes into the main branch of content, creating an updated version and a new entry in the space’s [version history](../content-editor/activity-history.md#see-the-activity-of-a-specific-draft).
+#### Diff view
-
Once you’re happy with your changes, you can click Merge to add the changes to the main branch.
+When you open the **Changes** tab in the space header, the diff view will appear. Diff view highlights every page and block that’s been edited in a change request. It will highlight any edited pages in the table of contents, and on the pages it will show the specific blocks that have been added, edited or removed.
-### Handling merge conflicts
+There are two options when using diff view:
-Sometimes, when you want to merge a change request, you may discover conflicts between the main content and the content you’re trying to merge. In the simplest form, a conflict is a piece of content that could not be merged automatically.
+1. **Show all pages** – This is the default mode for diff view, which will show both modified and non-modified pages in the table of contents. This is good for seeing which pages have been edited in the context of the entire space.
+2. **Show only changed pages** – This mode will show only the modified pages in the table of contents, which helps you focus on the changed content. This is particularly helpful in larger spaces with many pages and sub-pages.
-If this happens, you’ll be presented with a conflict alert, and a list of the conflicts you’ll need to resolve before continuing the merge.
+You can switch to the **Changes** tab to check the diff view in any change request.
-
You may experience a merge conflict — this menu should give you some context about what happened so you can resolve it.
+### Merging a change request
-### Resolving merge conflicts
+Merging a change request will add the change request’s changes into the main branch of content, creating an updated version and a new entry in the space’s [version history](../creating-content/version-control.md#see-the-activity-of-a-specific-draft).
-You have two options when it comes to resolving a merge conflict — **selecting a version to merge** or **manually** **editing the content**.
+#### Scheduling merges
-#### Selecting a version to merge
+If you prefer to merge change requests at a scheduled time—for example, to align with your product release cycles—you can use external tools like GitHub Actions or automation platforms such as Zapier, connected through [GitBook’s API](https://gitbook.com/docs/developers/gitbook-api/api-reference/change-requests#post-spaces-spaceid-change-requests-changerequestid-merge).
-You can resolve a merge conflict by selecting a version you want to merge — either your incoming content, or the content that was previously there. This allows you to choose between one change and another — either your recent work, or the original content.
+As an example, adding this GitHub workflow would merege a change request once a week:
-If you’re dealing with a merge conflict that can be resolved this way, you can select the version you want to keep, and the other version will be deleted.
+{% code title=".github/workflows/scheduled-gitbook-merge.yml" %}
+```yaml
+name: Scheduled GitBook Merge
-#### Manually editing
+on:
+ schedule:
+ - cron: '0 9 * * 3' # Runs every Wednesday at 09:00 UTC
-If you don’t want to choose between versions, you can resolve a merge conflict by manually editing the conflict. You’ll be able to delete the blocks you don’t need, or even rewrite them entirely. Once you’re happy with the changes, you can move on to the next conflict until they’re all resolved.
+jobs:
+ merge_changes:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Merge Change Request
+ run: |
+ curl -X POST https://api.gitbook.com/v1/spaces/{space-id}/change-requests/{change-request-id}/merge \
+ -H 'Authorization: Bearer YOUR_API_KEY' \
+ -H 'Content-Type: application/json'
+```
+{% endcode %}
-### Reviewing a change request
+{% hint style="info" %}
+Only [administrators, creators, and reviewers](../account-management/member-management/roles.md) can merge change requests.
+{% endhint %}
-If you get a request to review a change request, you'll be able to edit the content and leave feedback to make sure it's in good shape before it’s merged to the main version. You can either request changes if you think it still needs work, or approve the change request, to signal it's ready to merge.
+### Handling merge conflicts
+
+Sometimes, when you want to merge a change request, you may discover conflicts between the main content and the content you’re trying to merge. In the simplest form, a conflict is a piece of content that could not be merged automatically.
-Most reviews will take place in the change request’s [comments](comments-discussion.md), where collaborators can share feedback and have discussions about specific content blocks, or the change request as a whole.
+If this happens, you’ll be presented with a conflict alert, and a list of the conflicts you’ll need to resolve before continuing the merge.
-#### Diff view
+### Resolving merge conflicts
-Diff view allows you to toggle a view that makes it easy to see what’s been edited in a change request. It will highlight any edited pages in the space, and on the pages it will show the specific blocks that have been added, edited or removed.
+You have two options when it comes to resolving a merge conflict — **selecting a version to merge** or **manually** **editing the content**.
-There are two options for using diff view:
+#### Selecting a version to merge
-1. **All pages** - this is the default mode for diff view, which will show both modified and non-modified pages in the table of contents. This is good for seeing which pages have been edited in the context of the entire space.
-2. **Only changes** - this mode will show only the modified pages in the table of contents, which helps you focus on the changed content. This is particularly helpful in larger spaces with many pages and sub-pages.
+You can resolve a merge conflict by selecting a version you want to merge — either your incoming content, or the content that was previously there. This allows you to choose between one change and another — either your recent work, or the original content.
-You can toggle diff view on or off in any change request.
+If you’re dealing with a merge conflict that can be resolved this way, you can select the version you want to keep, and the other version will be deleted.
-
You can toggle diff mode on or off for any change request to make it easier to see what’s changed.
+#### Manually editing
-{% hint style="info" %}
-**Remember:** Members with an [editor](../account-management/member-management/roles.md#editor) role can create and submit requests, but only members with a [reviewer](../account-management/member-management/roles.md#reviewer) role or above can merge change requests.
-{% endhint %}
+If you don’t want to choose between versions, you can resolve a merge conflict by manually editing the conflict. You’ll be able to delete the blocks you don’t need, or even rewrite them entirely. Once you’re happy with the changes, you can move on to the next conflict until they’re all resolved.
### Archiving a change request
If you decide not to merge a change request and want to remove it from the queue, you can archive it.
-To archive a change request, first open it up. Then click the **Actions menu** in the top-right corner of the window and choose **Archive**. You can find and reopen archived change requests later by opening the **Change Requests** menu and selecting the **Archived** tab.
+To archive a change request, first open it up. Then click the **Actions menu** next to the change request’s title and choose **Archive**. You can find and reopen archived change requests later by opening the **Change Requests** menu and selecting the **Archived** tab.
diff --git a/collaboration/collaboration.md b/collaboration/collaboration.md
deleted file mode 100644
index 952bdebe..00000000
--- a/collaboration/collaboration.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-description: Collaborate with your team through comments and notifications.
-icon: bullseye-arrow
----
-
-# Overview
-
-GitBook gives you features that allow you to work asynchronously with your team.
-
-Explore the following sections to learn more about how to leave **comments** and view **notifications**.
-
-### Learn more about
-
-
Comments Leave comments on spaces, pages, and changes requests.
diff --git a/collaboration/collaboration/change-requests.md b/collaboration/collaboration/change-requests.md
index 646cf53b..d88a113b 100644
--- a/collaboration/collaboration/change-requests.md
+++ b/collaboration/collaboration/change-requests.md
@@ -6,7 +6,7 @@ description: Learn about editing with change requests
-
The change requests panel
+
The change requests panel
@@ -26,7 +26,7 @@ In a space that is **locked** for live edits, hit the ’Edit’ button in the s
-
Click the "Edit" button in the top right corner to start a change request
+
Click the "Edit" button in the top right corner to start a change request
@@ -42,7 +42,7 @@ Once you’re happy with your changes, you can **submit** the change request.
-
Submit your change request for review in the bottom right corner of the editor
+
Submit your change request for review in the bottom right corner of the editor
diff --git a/collaboration/collaboration/live-edits.md b/collaboration/collaboration/live-edits.md
index 547bd05f..4be5676a 100644
--- a/collaboration/collaboration/live-edits.md
+++ b/collaboration/collaboration/live-edits.md
@@ -26,7 +26,7 @@ You can lock or unlock space for live edits by selecting ’Unlock live edits’
-
Unlock live edits from the space actions menu
+
Unlock live edits from the space actions menu
diff --git a/collaboration/comments-discussion.md b/collaboration/comments-discussion.md
deleted file mode 100644
index 11160f3f..00000000
--- a/collaboration/comments-discussion.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-icon: comment
-description: Ask questions or receive feedback on the content you create in GitBook.
----
-
-# Comments
-
-Comments allow you to have as much (or as little) conversation as you like around specific pieces of content — without switching out of context from GitBook.
-
-### Add a comment to your content
-
-You can comment on any block within your content. Hover over a block and click the content icon that appears on the right of the block to open the **Comments** side panel with an empty comment. You can open this panel again by clicking on the **Comments** button in the [space header](../content-editor/editor/navigation.md#space-header).
-
-
Add a comment in GitBook.
-
-### Comment threads
-
-Any top-level comment in GitBook can be replied to, turning it into a discussion thread.
-
-### Reacting to comments
-
-You can also leave an emoji reaction on any comment by clicking the emoji button on the message or thread you’d like to react to.
-
-### Resolving comments
-
-If you’re done working through a comment thread or idea, you can **resolve** a comment at any time. Resolving a comment will hide it in the interface, but still keep it accessible in the ’Resolved’ tab of the space’s comments section.
-
-### Commenting and change requests
-
-In addition to commenting on a page or content block, you can also leave comments inside of a change request. See [change requests](change-requests.md) to learn more.
diff --git a/collaboration/comments.md b/collaboration/comments.md
new file mode 100644
index 00000000..70642347
--- /dev/null
+++ b/collaboration/comments.md
@@ -0,0 +1,30 @@
+---
+description: Ask questions to your team or receive feedback on the content you create
+icon: comment
+---
+
+# Comments
+
+Comments allow you to provide feedback around specific pieces of content — without switching out of context from GitBook.
+
+### Add a comment
+
+You can open the comments panel by clicking on the **Comments** button in the [space header](../resources/gitbook-ui.md#space-header).
+
+Adding a comment here will attach a comment to the entire page. You can also comment on a specific block by hovering over a block and clicking the content icon that appears on the right.
+
+You can tag teammates by typing the `@` symbol followed by their name.
+
+{% hint style="info" %}
+Guests will be able to make comments but they will not be able to see or mention other users in the organization.
+{% endhint %}
+
+### Comment threads
+
+You can reply to any comment to start a conversation with your teammates, turning it into a discussion thread.
+
+You can also leave an emoji reaction on any comment by clicking the emoji button on the message or thread you’d like to react to.
+
+### Resolving comments
+
+If you’re done working through a comment thread or idea, you can **resolve** a comment at any time. Resolving a comment will hide it in the interface, but still keep it accessible in the ’Resolved’ tab of the space’s comments section.
diff --git a/collaboration/live-edits.md b/collaboration/live-edits.md
new file mode 100644
index 00000000..0daa3941
--- /dev/null
+++ b/collaboration/live-edits.md
@@ -0,0 +1,31 @@
+---
+description: Edit pages in real-time with other collaborators
+icon: file-pen
+---
+
+# Live edits
+
+With live edits enabled, members in your org can edit a space without creating [a change request](change-requests.md). When editing content, you can see the avatars of anyone currently viewing the space in the top-right corner.
+
+GitBook supports live collaboration, meaning you’ll be able to work on the same document with multiple members at the same time.
+
+{% hint style="info" %}
+**Live edits are locked** by default in any newly created space. To edit the content, you will either need to [create a change request](change-requests.md), or toggle live edits on.
+{% endhint %}
+
+### Toggling live edit mode
+
+You can toggle live edit mode in a space by selecting **Lock live edits** or **Unlock live edits** from the [space header’s](../resources/gitbook-ui.md#space-header) **Actions menu** .
+
+When a space is in **Live edits** mode, the space header will show the **Editor** tab. When it is in **Locked live edits** mode, the space header will show a **Read-only** tab. When the Read-only tab appears in the space header, you will need to open a change request to edit the content of the page, or unlock live edits.
+
+### When is live editing _not_ available?
+
+You cannot unlock live editing if:
+
+1. a space is published with the **In collection**, **Public**, or **Unlisted** visibility option.
+2. a space has [GitHub or GitLab Sync](../getting-started/git-sync/) enabled.
+
+{% hint style="info" %}
+Only [administrators and creators](../account-management/member-management/roles.md) can lock or unlock live edits.
+{% endhint %}
diff --git a/collaboration/merge-rules.md b/collaboration/merge-rules.md
new file mode 100644
index 00000000..e037c3ef
--- /dev/null
+++ b/collaboration/merge-rules.md
@@ -0,0 +1,129 @@
+---
+description: Define requirements that must be met before change requests can be merged
+if: visitor.claims.unsigned.bucket.MERGE_RULES === true
+icon: file-shield
+---
+
+# Merge rules
+
+Merge rules allow you to define requirements that must be met before change requests can be merged, such as needing a review from a specific user, or requiring a subject or description for the change request.
+
+These rules help maintain content quality and ensure proper review processes across your documentation workflow.
+
+When you have merge rules configured, they’ll automatically evaluate change requests before they can be merged. If a rule isn’t satisfied, the merge will be blocked until the requirements are met.
+
+This provides an automated way to enforce your team’s collaboration and review standards.
+
+## Using merge rules
+
+You can configure merge rules at different levels to match your team’s workflow:
+
+### Organization-level configuration
+
+Organizations can set default merge rules that all spaces inherit. This provides consistency across multiple spaces while still allowing individual spaces to customize their rules as needed.
+
+To configure merge rules for your organization, open the organization menu at the top of the sidebar and choose **Settings** . In the Settings screen, select **Merge rules** under the **Organization** section of the sidebar. Here you can specify merge rules for your entire organization.
+
+Choose between unrestricted merging, or select from the list of presets to apply to change requests across your entire organization.
+
+### Space-level configuration
+
+Whether or not you have enabled organization-wide merge rules, each space can have its own merge requirements tailored to its content and team structure.
+
+This gives you the flexibility to have stricter rules for important documentation and more relaxed rules for draft content.
+
+When setting up merge rules for a space, you can choose to:
+
+* **Inherit** merge rules from your organization
+* **Define custom rules** specific to that space
+* **Disable merge rules** entirely
+
+{% hint style="info" %}
+If you inherit organization rules, any changes to the organization’s merge rules will automatically apply to the space.
+{% endhint %}
+
+To configure merge rules for your organization, open the **Actions menu** :ellipsis: in the top left of the editor, and then select **Merge rules**. Here you can specify whether to inherit the merge rules from your organization or configure new ones specific to that space.
+
+## Rule evaluation
+
+### How rules work
+
+When someone wants to merge a change request, GitBook will evaluate all the configured rules in order:
+
+* All rules in a configuration must pass for a merge to be allowed
+* Rules are evaluated in the order they appear in your configuration
+* If any rule fails, the merge is blocked with an appropriate error message
+* Rules with bypass capabilities can override previous failures
+
+### Bypass rules
+
+Some rules have bypass capabilities (like **Allow specified actors to bypass requirements**). These special rules can override other rule failures. If a bypass rule evaluates to true, the merge will be allowed even if other rules have failed.
+
+## Best practices
+
+When setting up merge rules, consider these recommendations:
+
+* **Start simple**: Begin with basic rules like requiring at least one review.
+* **Scale gradually**: Add more specific requirements as your team grows and workflows mature.
+* **Use bypass carefully**: Only grant bypass permissions to trusted administrators.
+* **Review regularly**: Adjust rules based on your team’s actual workflow patterns.
+* **Test first**: When possible, test rule changes in a test space before applying to production spaces.
+
+## Available rule types
+
+### Review requirements
+
+
Rule
Description
Require at least one review
Ensures that at least one team member has reviewed the change request before it can be merged.
Require all reviews approved
All completed (not requested) reviews must be approvals. If any reviewer has requested changes or rejected the change request, the merge will be blocked.
Require review by specified actors
Requires approval from all specified users. You can select specific team members who must review and approve the change request before it can be merged.
Require review by one of specified actors
Requires approval from at least one of the specified users. This is useful when you have multiple qualified reviewers but only need one approval from the group.
Require Docs Agent review (coming soon)
Requires a review from the GitBook AI agent. This ensures automated quality checks are performed on content changes before merging.
+
+### Change request requirements
+
+
Rule
Description
Require up to date change request
The change request must be current with the primary content branch. If the primary content has been updated since the change request was created, you’ll need to rebase or update it before merging.
Require subject
The change request must have a descriptive subject/title. Empty subjects will block the merge.
Require description
The change request must include a description explaining what changes were made and why.
+
+### Advanced options
+
+
Rule
Description
Allow specified actors to bypass requirements
You can designate specific users who are allowed to bypass all other merge rule requirements. This is useful for administrators or emergency situations where rules need to be overridden.
Custom expression
You can create advanced merge rules using custom JavaScript expressions. This allows you to define complex logic based on the evaluation context, with access to properties of the change request, reviews, and the user attempting to merge.
+
+#### Custom Expressions
+
+When you create a custom expression, it will be evaluated each time someone tries to merge a change request. If the expression returns `true`, the merge is allowed. If it returns `false`, the merge is blocked.
+
+{% hint style="info" %}
+Custom expressions support standard JavaScript syntax (ES2022) and have a maximum length of 1024 characters.
+{% endhint %}
+
+**Available context variables:**
+
+* `changeRequest.subject` - The subject/title of the change request
+* `changeRequest.description` - The description of the change request
+* `changeRequest.outdated` - Whether the change request is outdated (boolean)
+* `changeRequest.createdBy.id` - ID of the user who created the change request
+* `reviews` - Array of review objects, each containing:
+ * `reviews[].status` - Review status (`"approved"` or `"changes_requested"`)
+ * `reviews[].reviewer.id` - ID of the reviewer
+* `actor.id` - ID of the user attempting to merge
+
+**Common expression examples:**
+
+{% code title="Require multiple approved reviews" %}
+```javascript
+reviews.filter(r => r.status === "approved").length >= 2
+```
+{% endcode %}
+
+{% code title="Require approval from specific user" %}
+```javascript
+reviews.some(r => r.reviewer.id === "harry" && r.status === "approved")
+```
+{% endcode %}
+
+{% code title="Require description for urgent changes" %}
+```javascript
+!changeRequest.subject.includes("[URGENT]") || !!changeRequest.description
+```
+{% endcode %}
+
+{% code title="Allow self-merge only for minor changes" %}
+```javascript
+changeRequest.createdBy.id === actor.id ? changeRequest.subject.startsWith("[minor]") : true
+```
+{% endcode %}
diff --git a/collaboration/notifications.md b/collaboration/notifications.md
index 404b0e03..5eee03ac 100644
--- a/collaboration/notifications.md
+++ b/collaboration/notifications.md
@@ -2,34 +2,24 @@
icon: message-exclamation
description: >-
Receive notifications about new content, updates to your spaces or changes in
- visibility.
+ visibility
---
# Notifications
Notifications provide updates about the activity on GitBook that comes from spaces owned by you or an organization that you are a member of.
-{% hint style="info" %}
-**Permissions**
-
-All member roles can manage their own notifications.
-{% endhint %}
-
-You can receive notifications inside the GitBook app and/or via email. We support [several types of notifications](notifications.md#notification-types) which you can disable or enable in [notification settings](notifications.md#notification-settings).
+You can receive notifications inside the GitBook app and/or via email. We support [several types of notifications](notifications.md#notification-types) which you can disable or enable in your notification settings.
### App notifications
-You can find app notifications at the top of the [sidebar](../content-editor/editor/navigation.md#the-sidebar).
-
-{% hint style="info" %}
-Notification retention policy: we currently keep all notifications forever, but could change that in the future.
-{% endhint %}
+You can find app notifications at the top of the [sidebar](../resources/gitbook-ui.md#the-sidebar).
Within the notifications pop-up, you’ll see two icons in the top-right corner. You can either mark all of your notifications as read, or head to your notification settings to update your preferences.
### Email notifications
-Email notifications are enabled by default, and can be disabled in [your notifications settings](https://app.gitbook.com/account/notification). When enabled, GitBook will send one email per notification type. This will be sent to the email address associated with your personal GitBook account.
+Email notifications are enabled by default, and can be disabled in your notifications settings. When enabled, GitBook will send one email per notification type. This will be sent to the email address associated with your personal GitBook account.
These email will appear to be sent from `no-reply@gitbook.io via sendgrid.net`
@@ -37,19 +27,19 @@ These email will appear to be sent from `no-reply@gitbook.io via sendgrid.net`
As with all email delivery, there’s a chance that you might not receive the email. Possible reasons include but are not limited to:
-* Our email ends up in your spam folder or caught by another protection mechanism.
-* Emails sent from GitBook to your email address have bounced many times, and therefore further sending has been automatically blocked by our mail service.
-* There could be a temporary delivery problem that will resolve on its own.
-* A wrong expectation about the notifications you should be receiving.
-* A wrong expectation about the email address to which we would be sending the notification.
+- Our email ends up in your spam folder or caught by another protection mechanism.
+- Emails sent from GitBook to your email address have bounced many times, and therefore further sending has been automatically blocked by our mail service.
+- There could be a temporary delivery problem that will resolve on its own.
+- A wrong expectation about the notifications you should be receiving.
+- A wrong expectation about the email address to which we would be sending the notification.
If you think you might be running into any of these issues, here are some things you can try:
-* Check your spam or other protection mechanism and make sure our email address (`no-reply@gitbook.io`) is not blocked on your end.
-* Wait it out if you are aware of any temporary issue with your mail provider.
-* Check [your settings](https://app.gitbook.com/account/notification) to ensure that you have enabled email notifications for the type of notification you are expecting.
-* Make sure you are checking the correct email address. You can see the email address of your personal account in [your account settings](https://app.gitbook.com/account).
-* [Contact support](../help-and-faq/faq/support.md) if all other things fail. If you do, please make sure to include as much information as possible. For example, this might include the email address you expect to receive the notification to, the type of the notification (you can see that in the [settings](https://app.gitbook.com/account/notification)), and the exact details of what you feel should have triggered that notification for you. Please include links to anything relevant, as well.
+- Check your spam or other protection mechanism and make sure our email address (`no-reply@gitbook.io`) is not blocked on your end.
+- Wait it out if you are aware of any temporary issue with your mail provider.
+- Check [your settings](https://app.gitbook.com/account/notification) to ensure that you have enabled email notifications for the type of notification you are expecting.
+- Make sure you are checking the correct email address. You can see the email address of your personal account in [your account settings](https://app.gitbook.com/account).
+- [Contact support](https://gitbook.com/docs/help-center/support/how-do-i-contact-support) if all other things fail. If you do, please make sure to include as much information as possible. For example, this might include the email address you expect to receive the notification to, the type of the notification (you can see that in the [settings](https://app.gitbook.com/account/notification)), and the exact details of what you feel should have triggered that notification for you. Please include links to anything relevant, as well.
### Notification settings
@@ -59,7 +49,7 @@ For both app and email notifications, [you can configure](https://app.gitbook.co
We currently offer notifications for the following areas:
-* Spaces and collections
-* Change requests
-* Mentions in comments
-* Organizations
+- Spaces and collections
+- Change requests
+- Mentions in comments
+- Organizations
diff --git a/collaboration/pdf-export.md b/collaboration/pdf-export.md
new file mode 100644
index 00000000..6e9fd4bf
--- /dev/null
+++ b/collaboration/pdf-export.md
@@ -0,0 +1,37 @@
+---
+description: Export a PDF copy of your GitBook content
+icon: file-pdf
+---
+
+# PDF export
+
+### Allow readers to export a PDF version of your published content
+
+{% include "../.gitbook/includes/premium-and-ultimate-hint.md" %}
+
+To enable or disable PDF export for visitors to your [published docs site](broken-reference/), open the docs site’s dashboard, open the **Customization** tab, and navigate to **Configure → Page actions**. From there, you can toggle **Export as PDF** on or off.
+
+This setting determines whether or not **readers of your published content can download it in PDF format**. This feature is only available for **Premium and Ultimate sites**.
+
+### Export your own internal content as PDF
+
+However you decide to configure your published docs sites, all logged-in members of an organization on a Pro or Enterprise can export a page — or an entire space — from your internal knowledge base as a PDF file.
+
+{% hint style="warning" %}
+Note that links across spaces are not currently supported when exporting internal content to PDF.
+{% endhint %}
+
+#### Export an individual page
+
+1. Open the page you want to export, then open the page’s [Actions menu](../resources/gitbook-ui.md#the-actions-menu) next to the page title.
+2. Select **Export to PDF > Current page**.
+3. Wait for the page to load, then click the **Print or save as PDF** button in the upper right to open your browsers Print menu.
+4. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.
+
+#### Export an entire space
+
+1. Open the[ Actions menu](../creating-content/content-structure/) next to the page title and choose **Export as PDF > All pages**. Alternatively, open the space’s **Actions menu** in the [space header](../resources/gitbook-ui.md#space-header) and choose **Export as PDF** in the drop-down menu.\
+ \
+ &#xNAN;_Note: This action is not available within a change request._
+2. Wait for the page to load, then click the **Print or save as PDF** button in the upper right to open your browsers Print menu.
+3. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.
diff --git a/collaboration/share.md b/collaboration/share.md
new file mode 100644
index 00000000..8f149492
--- /dev/null
+++ b/collaboration/share.md
@@ -0,0 +1,48 @@
+---
+description: Collaborate with your teammates on spaces, collections and more
+icon: user-plus
+---
+
+# Inviting your team
+
+
Invite your team to GitBook to collaborate on pages, spaces, and published sites.
+
+### Sharing a space or collection
+
+To share a space or collection, click the **Share** button in the top-right corner. This will open the share modal.
+
+Inside the share modal, you’ll see different sharing options along the top.
+
+By default, every member of your organization can see all the content in your organization. However, their permissions are inherited from the [role](../account-management/member-management/roles.md) assigned to them within your [Organization settings](../account-management/organization-settings.md).
+
+You can see everyone who access, and their level of access, in the share modal. You can also make changes to these settings here.
+
+### Invite members
+
+#### Invite a person or team from your organization
+
+Some people in your team may not have access to a specific space in your GitBook organization due to their role or specific permissions settings. To invite someone who’s already a member of your organization, simply type their name, choose their role for this space, and hit Invite.
+
+You can also add a [team](../account-management/member-management/teams.md) by typing the team name and hitting Invite.
+
+#### Invite someone from outside your organization
+
+To invite someone from outside your organization, simply add their email address, choose their role, and hit **Invite**. When you choose their role, you can also choose to leave the **Invite as an organization member** toggle switched on to make them a full member of your organization, with access to all your team’s content when they’re logged in.
+
+Alternatively, toggle this off to invite them as a [guest](../account-management/member-management/roles.md#guest-role). Guests only have access to the individual spaces that you invite them to, and can be given a specific role within that space — whether it’s to edit the content, or only view and comment on it.
+
+{% hint style="warning" %}
+Inviting someone either as a full member or a guest will make them a member of the organization that owns the space, which **will increase your overall subscription charge.**
+
+The cost for this will depend on [your organization’s plan](../account-management/plans/).
+{% endhint %}
+
+It is also possible to [invite members to the organization ](../account-management/member-management/invite-members-to-your-organization.md)from within the **Organization settings** area.
+
+#### Invite guests via link
+
+If you don’t want to use email to invite someone to your content, or want to invite a number of people as guests quickly, you can create a secret link. You can also set the role of guests that join using the link, so you have control over who can do what to your content.
+
+When you share this link, anyone who clicks on it will be able to sign up, join your organization as a [guest](../account-management/member-management/roles.md#guest-role), and get access to just this single space and its content.
+
+You can revoke the link at any time by opening the **Actions menu** next to the link and choosing **Revoke**.
diff --git a/collaboration/share/README.md b/collaboration/share/README.md
deleted file mode 100644
index 870554ad..00000000
--- a/collaboration/share/README.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-icon: user-group
-description: >-
- Discover how you can collaborate with your team when editing your GitBook
- content.
----
-
-# Share your content
-
-When working on your content, GitBook offers different ways to collaborate with your team. There are different options for sharing a single space or a collection with your team.
-
-### Learn more
-
-
-
diff --git a/collaboration/share/pdf-export.md b/collaboration/share/pdf-export.md
deleted file mode 100644
index fe80af62..00000000
--- a/collaboration/share/pdf-export.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-description: Export a PDF copy of your GitBook content.
----
-
-# PDF export
-
-{% hint style="info" %}
-This feature is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-### Allow readers to export a PDF version of your published content
-
-{% hint style="info" %}
-**Permissions**
-
-[Admins and creators](../../account-management/member-management/roles.md) can enable and disable PDF export for a space.
-{% endhint %}
-
-To enable or disable PDF export for visitors to your [published docs site](broken-reference), open the docs site’s dashboard and click the **Settings** tab.
-
-You can enable PDF export by toggling it on in the **Customization** section.
-
-This setting determines whether or not **readers of your published content can download it in PDF format**. This feature is only available for **Standard and Premium sites**.
-
-
-
-### Export your own internal content as PDF
-
-However you decide to configure your published docs sites, all logged-in members of an organization on a Pro or Enterprise can export a page — or an entire space — from your internal knowledge base as a PDF file.
-
-#### How to export an individual page
-
-1. Open the page you want to export, then open the page’s [Actions menu](../../content-editor/editor/navigation.md#the-actions-menu) next to the page title.
-2. Select **Export to PDF > Current page**.
-3. Wait for the page to load, then click the **Print or save as PDF** button in the upper right to open your browsers Print menu.
-4. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.
-
-
Export a PDF of a single page.
-
-#### How to export an entire space
-
-1. Open the[ Actions menu](../../content-editor/editor/content-structure/) next to the page title and choose **Export as PDF > All pages**. Alternatively, open the **Space options** menu on the far right of the space header and choose **Export as PDF** in the drop-down menu.
-2. Wait for the page to load, then click the **Print or save as PDF** button in the upper right to open your browsers Print menu.
-3. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.
-
-
Export a PDF of an entire space.
diff --git a/collaboration/share/share-a-collection.md b/collaboration/share/share-a-collection.md
deleted file mode 100644
index 87a062fb..00000000
--- a/collaboration/share/share-a-collection.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-description: Collaborate with your team on a group of spaces within a GitBook collection.
----
-
-# Share a collection
-
-### Sharing a collection
-
-To share a collection, click the **Share** button in the top-right corner of a collection. This will open the share modal.
-
-
Share a collection
-
-Inside the share modal, you’ll see different sharing options along the top.
-
-{% hint style="info" %}
-The options available to you will depend on your permissions in the space, as well as [your organization’s plan](../../account-management/plans/).
-{% endhint %}
-
-By default, every member of your organization can see all the content in your organization. But their permissions are inherited from the [role](../../account-management/member-management/roles.md) assigned to them within the [**Organization settings**](../../account-management/organization-management.md) area.
-
-You can see everyone who access to your collection, and their level of access, in the share modal. You can also make changes to those access settings in this menu.
-
-### Invite members
-
-
Invite members
-
-#### Invite a person or team from your organization
-
-Some people in your team may not have access to a specific collection in your GitBook organization due to their role or specific permissions settings. To invite someone who’s already a member of your organization, simply type their name, choose their role for this collection, and hit Invite.
-
-You can also add a whole [team](../../account-management/member-management/teams.md) to a collection by typing the team name and hitting Invite.
-
-#### Invite someone from outside your organization
-
-To invite someone from outside your organization, simply add their email address, choose their role, and hit **Invite**. When you choose their role, you can also choose to leave the **Invite as an organization member** toggle switched on to make them a full member of your organization, with access to all your team’s content when they’re logged in.
-
-Alternatively, toggle this off to invite them as a [guest](../../account-management/member-management/roles.md#guest-role). Guests only have access to the individual collections that you invite them to, and can be given a specific role within that cikkection — whether it’s to edit the content, or only view and comment on it.
-
-{% hint style="warning" %}
-Inviting someone either as a full member or a guest will make them a member of the organization that owns the collection, which **will increase your overall subscription charge.**
-
-The cost for this will depend on [your organization’s plan](../../account-management/plans/).
-{% endhint %}
-
-It is also possible to [invite members to the organization ](../../account-management/member-management/invite-members-to-your-organization.md)from within the **Organization settings** area.
-
-#### Invite guests via link
-
-If you don’t want to use email to invite someone to your content, or want to invite a number of people as guests quickly, you can create a secret link. You can also set the role of guests that join using the link, so you have control over who can do what to your content.
-
-When you share this link, anyone who clicks on it will be able to sign up, join your organization as a [guest](../../account-management/member-management/roles.md#guest-role), and get access to just this single collection and its content.
-
-You can revoke the link at any time by opening the **Actions menu** next to the link and choosing **Revoke**.
diff --git a/collaboration/share/share-a-space.md b/collaboration/share/share-a-space.md
deleted file mode 100644
index f900d5e7..00000000
--- a/collaboration/share/share-a-space.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-description: Collaborate with your team on a GitBook space.
----
-
-# Share a space
-
-### Sharing a space
-
-To share a space, click the **share** button in the top-right corner of a space. This will open the share modal.
-
-
Share a space
-
-Inside the share modal, you’ll see different sharing options along the top.
-
-{% hint style="info" %}
-The options available to you will depend on your permissions in the space, as well as [your organization’s plan](../../account-management/plans/).
-{% endhint %}
-
-By default, every member of your organization can see all the content in your organization. But their permissions are inherited from the [role](../../account-management/member-management/roles.md) assigned to them within the [**Organization settings**](../../account-management/organization-management.md) area.
-
-You can see everyone who access to your space, and their level of access, in the share modal. You can also make changes to those access settings in this menu.
-
-### Invite members
-
-
Invite members
-
-#### Invite a person or team from your organization
-
-Some people in your team may not have access to a specific space in your GitBook organization due to their role or specific permissions settings. To invite someone who’s already a member of your organization, simply type their name, choose their role for this space, and hit Invite.
-
-You can also add a whole [team](../../account-management/member-management/teams.md) to a space by typing the team name and hitting Invite.
-
-#### Invite someone from outside your organization
-
-To invite someone from outside your organization, simply add their email address, choose their role, and hit **Invite**. When you choose their role, you can also choose to leave the **Invite as an organization member** toggle switched on to make them a full member of your organization, with access to all your team’s content when they’re logged in.
-
-Alternatively, toggle this off to invite them as a [guest](../../account-management/member-management/roles.md#guest-role). Guests only have access to the individual spaces that you invite them to, and can be given a specific role within that space — whether it’s to edit the content, or only view and comment on it.
-
-{% hint style="warning" %}
-Inviting someone either as a full member or a guest will make them a member of the organization that owns the space, which **will increase your overall subscription charge.**
-
-The cost for this will depend on [your organization’s plan](../../account-management/plans/).
-{% endhint %}
-
-It is also possible to [invite members to the organization ](../../account-management/member-management/invite-members-to-your-organization.md)from within the **Organization settings** area.
-
-#### Invite guests via link
-
-If you don’t want to use email to invite someone to your content, or want to invite a number of people as guests quickly, you can create a secret link. You can also set the role of guests that join using the link, so you have control over who can do what to your content.
-
-When you share this link, anyone who clicks on it will be able to sign up, join your organization as a [guest](../../account-management/member-management/roles.md#guest-role), and get access to just this single space and its content.
-
-You can revoke the link at any time by opening the **Actions menu** next to the link and choosing **Revoke**.
-
-### Publishing your content
-
-{% hint style="info" %}
-Looking to publish your content to the web? Head to the [published documentation](broken-reference) section to learn more.
-{% endhint %}
diff --git a/content-creation/activity-history.md b/content-creation/activity-history.md
deleted file mode 100644
index 05409e64..00000000
--- a/content-creation/activity-history.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-description: Learn how to monitor changes, roll back to a previous point in time, and more.
----
-
-# Version control
-
-You can easily monitor all changes submitted to your content thanks to the **history** tab. Here, your changes are split into two sections: **feed**, where you can see the day-to-day actions that have occurred within a given space, and **change history**, where you can specifically track changes to your space’s content.
-
-{% hint style="info" %}
-**Permissions**
-
-Only administrators can access the history tab, where they can view actions and change history in a space.
-{% endhint %}
-
-## Feed
-
-The activity feed is where you can get a bird’s eye view of what’s been going on in any given space. This is useful if you’ve been away from the action for a few days and want to catch up. It’s also useful if you’re curious about anything that’s happened in the space, e.g., when a specific member was added to the space, or when [live edits](../collaboration/collaboration/live-edits.md#toggling-live-edit-on-or-off) were locked or unlocked.
-
-
-
-
The activity feed for a space.
-
-
-
-## Change History
-
-The change history of a space is where you can specifically see actions that result in content changing. These include:
-
-- When [live edits](../collaboration/collaboration/live-edits.md) have been made on the space.
-- When a [change request](../collaboration/collaboration/change-requests.md) has been merged.
-- When a [Git Sync](../integrations/git-sync/) operation has been performed.
-
-## Version control
-
-### Viewing historical versions of content
-
-To view past versions of your content and any changes that were made, navigate to the hourglass icon in the top right-hand corner of the space [sub-navigation](../product-tour/navigation.md#space-sub-navigation). You can click on any item in the change history list to view how your content looked at the point this change was made. This is very similar to how [change requests](../collaboration/collaboration/change-requests.md) are viewed.
-
-
-
-
How to acccess your historical content
-
-
-
-### Rolling back to a previous version
-
-Rolling back allows you to revert a space’s content to a previous point in time. This is helpful if you’ve accidentally made a breaking change or deleted content and need to quickly get back to a previous version of the space.
-
-Admins and creators can click the **rollback** button while viewing a specific history item to roll the space back to this point in time.
-
-
-
-
Viewing a previous point in time via the change history
-
-
-
-{% hint style="info" %}
-For as long as a space exists in GitBook, no version of its content is deleted. Content is versioned and immutable.
-{% endhint %}
diff --git a/content-creation/blocks/README.md b/content-creation/blocks/README.md
deleted file mode 100644
index 249750ee..00000000
--- a/content-creation/blocks/README.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-description: Space content blocks
----
-
-# Blocks
-
-You can choose any of the following content blocks via the command palette:
-
-* [Paragraph](paragraph.md)
-* [Heading](heading.md)
-* [Unordered list](unordered-list.md)
-* [Ordered list](ordered-list.md)
-* [Task list](task-list.md)
-* [Hint](hint.md)
-* [Quote](quote.md)
-* [Code block](code-block.md)
-* [Insert files...](insert-files.md)
-* [Insert images...](insert-images.md)
-* [Embed a URL...](embed-a-url.md)
-* [Table](table.md)
-* [Cards](cards.md)
-* [Tabs](tabs.md)
-* [Expandable](expandable.md)
-* [Drawing](drawing.md)
-* [Math & TeX](math-and-tex.md)
-* [API method](api-method.md)
-* [OpenAPI](openapi.md)
-* [Page link](page-link.md)
-
-### Command palette
-
-You can invoke the command palette for adding a block with the cursor in an empty paragraph in two ways:
-
-1. Hitting the keyboard shortcut, which is `/` on both Mac and PC.
-2. Clicking :heavy\_plus\_sign: using your mouse. The icon appears in the left margin of the paragraph that has the current focus.
-
-### Exiting a block
-
-Some content blocks capture the editing cursor to allow you to add content in the context of that block. When you are done, you can continue adding new content to the page either by inserting a new paragraph below or above the content block, or by hitting `command` + `enter` on a Mac or `control` + `enter` on a PC.
-
-The example below shows how to exit [a quote content block](./#quote):
-
-
Exit editing a content block
-
-### Inserting a new content block
-
-You can insert a new content block below or above an existing block using your mouse:
-
-1. Hover over the editor at the position you need the new content block
-2. Click on the + icon that will appear
-3. Select the block from the drop-down menu to insert it in that position
-
-
Inserting a new block
-
-### Selecting blocks and interacting with selected blocks
-
-You can select blocks by pressing the `Esc` key.
-
-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 `Up` and `Down` keys
-* Copy the entire block using `Ctrl` + `C` (Windows) or `Cmd` + `C` (Mac)
-* Cut the entire block using `Ctrl` + `X` (Windows) or `Cmd` + `X` (Mac)
-* Delete the selected block(s) using `Del`
-
-### New: Full-width blocks :tada:
-
-By making your blocks full-width, you can create a clear visual hierarchy in your content. This is perfect for giving images and tables more space to breathe, but it looks great with a whole range of block types:
-
-* Cards
-* Tables
-* Code Blocks
-* Integrations
-* API Blocks
-* Image blocks
-
-#### Convert a block to full width:
-
-1. Insert a block into your page
-2. Click on icon next to your block and select full width
-
-
-
-{% hint style="warning" %}
-Text blocks such as paragraphs are not possible to convert to full width. If you do not see the option to convert your block, it is likely not included on the list of compatible blocks above.
-{% endhint %}
-
-#### Example of a full-width table block
-
-
Project
Owner
Completeness
Project A
Mike
4
Project B
Jack
3
Project C
Samantha
5
-
diff --git a/content-creation/blocks/api-method.md b/content-creation/blocks/api-method.md
deleted file mode 100644
index ad2ec9d9..00000000
--- a/content-creation/blocks/api-method.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-description: API method content block
----
-
-# API method
-
-An API Method block is used to manually document an HTTP API endpoint.
-
-### Example of API Method block
-
-{% swagger method="get" path="/user" baseUrl="https://api.example.com/v1" summary="Get a user" %}
-{% swagger-description %}
-Use this method to get information about a user
-{% endswagger-description %}
-{% endswagger %}
-
-{% hint style="info" %}
-You can now convert the API blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-#### Please also check:
-
-{% content-ref url="openapi.md" %}
-[openapi.md](openapi.md)
-{% endcontent-ref %}
-
-## Representation in Markdown
-
-```
-# API
-
-{% raw %}
-{% swagger method="get" path="" baseUrl="" summary="" %}
-{% swagger-description %}
-
-{% endswagger-description %}
-{% endswagger %}
-{% endraw %}
-```
diff --git a/content-creation/blocks/cards.md b/content-creation/blocks/cards.md
deleted file mode 100644
index e28d8f2a..00000000
--- a/content-creation/blocks/cards.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-description: Card content block
----
-
-# Cards
-
-Cards allow you to create a new visually pleasing page layout with text and images. They can be used to build landing pages or display any other content in a non-linear way.
-
-You can select large or medium-sized cards and link them to the relevant resources.
-
-### Example of a card
-
-
-
-{% hint style="info" %}
-You can now convert card blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-### How to create a card
-
-Type / to open the block insert palette. Then select `Cards` block. By clicking on\
-you can add and format text. You can also add additional columns such as numbers, user or rating.
-
-#### Adding links and images to your cards
-
-By clicking on the symbol you can add a target link (recommended), add [cover images](#user-content-fn-1)[^1] or delete the card completely.
-
-{% hint style="success" %}
-When creating cards, we recommend you use **target links instead of hyperlinks**. Target links will ensure that the reader is redirected to the intended destination, regardless of where they click within the card.
-{% endhint %}
-
-The key to great looking cards is editing your images so that they have the same ratio. For example:
-
-- 16:9 (eg. 1920px x 1080px)
-- 4:3 (eg. 1024X768)
-- 1:1 (eg. 500px x 500px)
-
-By using the same ratio for all of your images you can ensure that they will align when displayed on the page. This means that titles and text under images is also aligned, which provides a better reading experience.
-
-#### Card size
-
-You can select the card size by clicking onmenu to the left of your card block. The ’Medium’ option creates three cards in one horizontal line, while the ’Large’ option allows for only two cards to be created.
-
-[^1]: cover images can be icons or other small images that will help the reader grasp the content of your card
diff --git a/content-creation/blocks/code-block.md b/content-creation/blocks/code-block.md
deleted file mode 100644
index 45330957..00000000
--- a/content-creation/blocks/code-block.md
+++ /dev/null
@@ -1,117 +0,0 @@
----
-description: >-
- Show code snippets or whole files with syntax highlighting using code blocks.
- We are using Prism for syntax highlighting.
----
-
-# Code block
-
-You can show code on GitBook using code blocks. You can choose to [set the syntax](code-block.md#set-syntax...), [show line numbers](code-block.md#with-line-numbers), [show a caption](code-block.md#with-caption), and [wrap the lines](code-block.md#wrap-code). There is also a convenient way to [copy the contents of a code block to the clipboard](code-block.md#copying-the-code).
-
-A code block may be useful for:
-
-- Sharing configuration
-- Code snippets
-- Code files
-- Showing usage examples of command line utilities
-- Showing how to call API endpoints
-- and for many more scenarios...
-
-### 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 the [tabs content block](tabs.md) to offer the same example in multiple 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 %}
-
-{% hint style="info" %}
-You can now convert code blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-### Options
-
-#### Set syntax...
-
-You can set the syntax to any of the supported languages and that will enable syntax highlighting in that language.
-
-{% hint style="info" %}
-We use [Prism](https://github.com/PrismJS/prism) for syntax highlighting. Here’s an easy way to check which languages Prism supports: [Test Drive Prism](https://prismjs.com/test.html#language=markup). If you notice a mismatch between GitBook and Prism, there’s a chance we are a version or two behind. We’ll catch up soon!
-{% endhint %}
-
-#### With line numbers
-
-Toggle showing line numbers. Showing line numbers is useful when the code represents the contents of a file as a whole and it makes sense to have them shown. Hiding line numbers is useful for snippets, usage instructions for command line or terminal expressions and similar scenarios.
-
-#### With caption
-
-A code block can have a caption. The caption is often the name of a file as shown in our [example](code-block.md#example), but it can be used as a title, or anything else you’d like.
-
-#### Wrap code
-
-Depending on what the code snippet represents you may or may not want to wrap lines. Wrapping lines is useful when your code is long and you want to avoid having the viewer scroll back and forth to read it. Wrapping often goes well with showing line numbers as that makes it easier to read the code and understand where each new line starts.
-
-### Actions
-
-#### Copying the code
-
-You can hover over a code block and see an icon that allows you to copy the contents of the code block to the clipboard in one click:
-
-
Copy code block contents to the clipboard
-
-### Representation in Markdown
-
-````markdown
-{% raw %}
-{% 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 %}
-{% endraw %}
-````
diff --git a/content-creation/blocks/drawing.md b/content-creation/blocks/drawing.md
deleted file mode 100644
index 0e44ed5f..00000000
--- a/content-creation/blocks/drawing.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-description: Drawing content block
----
-
-# Drawing
-
-Drawings / sketches can be inserted from the insertion palette and are editable directly through GitBook using the integrated [Excalidraw](https://excalidraw.com/) editor.
-
-Drawings are stored as special SVG files in the space. Those files have an extension of `drawing.svg`.
-
-### Example of a drawing block
-
-
-
diff --git a/content-creation/blocks/embed-a-url.md b/content-creation/blocks/embed-a-url.md
deleted file mode 100644
index 9e2f15fc..00000000
--- a/content-creation/blocks/embed-a-url.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-description: Embed a URL content block
----
-
-# Embed a URL
-
-To add a rich embed, simply paste the link of the content you want to embed and press the enter key! ✨ Note that the content you wish to embed must be publically available in order for GitBook to access the file. For example, when embedding a Google doc the share link that you paste into GitBook must be set to ’Anyone with the link’.
-
-
-
-{% hint style="info" %}
-You can now convert embed blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-### Examples of a rich embed
-
-### Videos
-
-{% embed url="https://www.youtube.com/watch?v=D_uLM5i0Z4c" %}
-
-### Codepens
-
-{% embed url="https://codepen.io/davidkpiano/pen/wMqXea" %}
-
-### Medium article
-
-{% embed url="https://medium.com/@jdan/i-peeked-into-my-node-modules-directory-and-you-wont-believe-what-happened-next-b89f63d21558" %}
-
-### Spotify music
-
-{% embed url="https://open.spotify.com/track/4FmiciU3ZmfgABlbCSXcWw?si=65zMAhStT2ivTit-kZISWg" %}
-
-### Git Sync representation in Markdown
-
-```markdown
-{% raw %}
-{% embed url="URL_HERE" %}
-{% endraw %}
-```
diff --git a/content-creation/blocks/expandable.md b/content-creation/blocks/expandable.md
deleted file mode 100644
index 98a10715..00000000
--- a/content-creation/blocks/expandable.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Expandable
-
-Expandable blocks are helpful in condensing what could otherwise be a lengthy paragraph. They are also great in step-by-step guides.
-
-### Example
-
-
-
-Step 1: Start using expandable blocks
-
-To add an expandable block select ⌘/ or Ctrl/ and select expandable blocks.
-
-
-
-
-
-Step 2: Add content to your block
-
-Once you’ve inserted an expandable block, you can add content including lists and code blocks within it.
-
-- [x] Done!
-
-
-
-## Representation in Markdown
-
-```
-# Expandable blocks
-
-
-
-Expandable block
-
-
-
-
-```
diff --git a/content-creation/blocks/heading.md b/content-creation/blocks/heading.md
deleted file mode 100644
index f4962d62..00000000
--- a/content-creation/blocks/heading.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-description: Structure your documents using headings
----
-
-# Heading
-
-GitBook offers 3 levels of headings, [which should be enough to properly structure your content](https://practicaltypography.com/headings.html). Headings structure your documents. Heading levels 1 and 2 will appear in the page outline.
-
-All headings have anchor links, which are links that you can use to point to a particular section of your documentation.
-
-You can see the anchors of a title when your content is in read mode. If you want to make some text point to an anchor within a page in your space, you can add a [relative link](../editor/rich-text.md#relative-links).
-
-{% hint style="info" %}
-Reading on a screen is less comfortable than reading on paper. Make sure your content is not too long with too many titles. Sometimes splitting your content into different pages creates a better overview! 🤓
-{% endhint %}
-
-### Example of a heading
-
-## My heading 1
-
-### My heading 2
-
-#### My heading 3
-
-### Representation in Markdown
-
-{% code overflow="wrap" %}
-```
-# My heading 1
-## My heading 2
-### My heading 3
-```
-{% endcode %}
diff --git a/content-creation/blocks/hint.md b/content-creation/blocks/hint.md
deleted file mode 100644
index a7171fab..00000000
--- a/content-creation/blocks/hint.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-description: Hint content block
----
-
-# Hint
-
-Hints are a great way to bring the reader’s attention to specific elements in your documentation.
-
-There are 4 different types of hints, and both [inline content](../editor/inline.md) and [formatting](../editor/formatting.md) are supported.
-
-### Example of a hint
-
-{% 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" %}
-**This is a heading**
-
-This is a line
-
-This is an inline image
-
-This is a second line
-{% endhint %}
-
-### Representation in Markdown
-
-```markdown
-{% raw %}
-{% 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" %}
-
-### This is a heading
-
-This is a line
-
-This is an inline image
-
-This is a second line
-{% endhint %}
-{% endraw %}
-```
diff --git a/content-creation/blocks/insert-files.md b/content-creation/blocks/insert-files.md
deleted file mode 100644
index 27fd31aa..00000000
--- a/content-creation/blocks/insert-files.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-description: Insert files content block
----
-
-# Insert files
-
-You can upload file assets to your GitBook space and include them in your spaces for download.
-
-### Example of file
-
-{% file src="../../../.gitbook/assets/hello-world.pdf" %}
-Hello world
-{% endfile %}
-
-### Related
-
-If you are looking to embed external content into your pages, take a look at how to [embed a URL](embed-a-url.md).
-
-## Uploading a file
-
-Files are managed in the files panel of your space. To access the files panel, click on files in the [space sub-navigation](https://docs.gitbook.com/getting-started/overview#space-sub-navigation).
-
-To upload a file, select **browse files** and use your system file dialog to select the file you want to upload.
-
-Files can also be uploaded as part of the image block setup flow, and the OpenAPI block setup flow. Upon creation, each of these blocks will open the files panel and have you either select or upload a new file.
-
-{% hint style="info" %}
-You can drag images from your file system directly into the editor, or paste a copied image into your content, and they will also appear in the files menu for the respective space.
-{% endhint %}
-
-## Managing files
-
-You can search for, rename, or delete files in your space in the files panel of your space. Below the file upload section, you’ll find the file listing. Each file has an action menu that lets you download, replace, rename, or delete your file. At the top of the file listing section, there is a search box, where you can search for your file by its name, and a sort toggle, which will let you sort your files by the date they were last modified, or their size.
-
-
Upload, filter, download, replace, edit, and delete files.
-
-### Renaming a file
-
-To rename a file, open the action 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 action 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. Be sure to update your documents that referred to your now deleted file! Otherwise, you may end up with some empty blocks.
-
-### Replacing a file
-
-GitBook supports replacing an existing file. 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 now refer to the new file after replacement.
-
-This can be helpful if you have, for example, a screenshot of your UI used throughout your space and want to change it in every case after a major product redesign. Replacing the file would cause it to be replaced everywhere it is used in the space, so you don’t have to manually update each instance of the screenshot.
-
-{% hint style="info" %}
-Once you’ve uploaded an image or a file, you can reference it anywhere in your space by using an image or a file block. It’s recommended you do this rather than dragging and dropping or pasting an image into the editor every time you want to include it.
-{% endhint %}
-
-To replace a file, open the action menu for the file and click **replace**. You’ll be presented with a file replacement dialog. Select the new file, and wait for the upload indicator to complete. Your new file will be displayed wherever your previous one was.
diff --git a/content-creation/blocks/insert-images.md b/content-creation/blocks/insert-images.md
deleted file mode 100644
index df8a6b6a..00000000
--- a/content-creation/blocks/insert-images.md
+++ /dev/null
@@ -1,128 +0,0 @@
----
-description: Insert images content block
----
-
-# Insert images
-
-You can insert full-width images into your space, which can be aligned to the left, center, or right. You can optionally include alt text and/or a caption. For accessibility purposes, we highly recommend setting alt text.
-
-### Example of an image block
-
-Image blocks can display a gallery of images, like this:
-
-  
-
-{% hint style="info" %}
-You can now convert image blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-### Light & Dark mode
-
-You’re able to 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 choose an image for light or dark mode, click the “Replace image” button while hovering over your image.
-
-
Setting a Light or Dark mode image
-
-{% hint style="warning" %}
-Note that light and dark mode images are not yet supported in some cases like Page covers or Card covers.
-{% endhint %}
-
-### Light & Dark mode through GitHub/GitLab Sync
-
-You can also add light & 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 with text around them), use the `` HTML element with a `` in it:
-
-```html
-Text before the image
-
-
-and text after the image
-```
-
-{% hint style="warning" %}
-Note that we are not yet supporting [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
-
-Hover over your image, and you’ll see the SIZE control appear in the top-right corner. Click on it to change the size of your image from the available options.
-
-
-
-- **Full** - removes all size specifications and displays either a full size or capped at a maximum width of **735** **pixels** for larger images
-- **Small** - 25% of the image size
-- **Medium** - 50% of the image size
-- **Large** - 75% of the image size
-
-In the event that the image exceeds the size of the editor, the image’s width will be limited to the ratio of the editor’s width instead.
-
-{% hint style="info" %}
-When it comes to resizing images in an image gallery, the process and results can differ from resizing single images.
-{% 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 of specifying the image dimensions are:\
-\
-``\
-``
-
-### Related
-
-If you are looking to embed external content into your pages, take a look at how to [embed a URL](embed-a-url.md).
-
-### Representation in Markdown
-
-```markdown
-//Simple Block
-
-
-//Block with Caption
-
-
-//Block with Alt text
-
-
-
-//Block with Caption and Alt text
-
-
GitBook Logo
-```
diff --git a/content-creation/blocks/math-and-tex.md b/content-creation/blocks/math-and-tex.md
deleted file mode 100644
index 02a3b9fe..00000000
--- a/content-creation/blocks/math-and-tex.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: Math & TeX content block
----
-
-# Math & TeX
-
-You can use mathTeX format to include mathematical formulae in your documentation. We offer that throught the [KaTeX](https://katex.org/docs/supported.html) library.
-
-We also offer this [as inline content](broken-reference).
-
-### Example of Math & TeX block
-
-$$
-s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
-$$
-
-
-
-### Representation in Markdown
-
-$$f(x) = x * e^{2 pi i \xi x}$$
-
-```
-# Math and TeX block
-
-$$f(x) = x * e^{2 pi i \xi x}$$
-```
diff --git a/content-creation/blocks/openapi.md b/content-creation/blocks/openapi.md
deleted file mode 100644
index b266d6ec..00000000
--- a/content-creation/blocks/openapi.md
+++ /dev/null
@@ -1,94 +0,0 @@
----
-description: >-
- OpenAPI content block. It allows using swagger files or external public URLs
- to reuse your existing API representation.
----
-
-# OpenAPI
-
-You can also sync with an OpenAPI or Swagger file or URL to include auto-generated methods in your documentation.
-
-### Example of an OpenAPI block
-
-{% swagger src="https://petstore.swagger.io/v2/swagger.json" path="/pet/{petId}" method="get" %}
-[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json)
-{% endswagger %}
-
-Manually writing documentation for your REST API can be time-consuming. To help, GitBook supports importing OpenAPI documents, which describe your API, and provides API Blocks to automatically represent your API methods based on the specification you provide, either as a file or as a URL for GitBook to load.
-
-GitBook supports [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) or [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) compliant files.
-
-### Creating an OpenAPI Block using your OpenAPI file
-
-Once you have an OpenAPI compliant representation of your API, you can use it in your documentation.
-
-#### **1. Create a new OpenAPI block** using the command palette, and select OpenAPI.
-
-
-
-{% hint style="info" %}
-You can now convert API blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-#### 2. Either:
-
-- **Upload** your OpenAPI formatted file, _or_
-- Provide a **URL** to your publicly available OpenAPI file.
-
-
-
-If you’re providing a **URL**, make sure that the file is available on the open internet, and that it’s not behind any kind of password protection.
-
-If you’re just experimenting, you can use one of the [default Swagger files](https://petstore.swagger.io/#/):
-
-`https://petstore.swagger.io/v2/swagger.json`
-
-#### **3. Check out your OpenAPI block!**
-
-OpenAPI blocks can be expanded and collapsed to show and hide more detail about the API endpoint.
-
-
-
-#### **4. Choose your API operation**
-
-To change the operation that your swagger block is showing, use the "Choose API Operation" option in the block menu
-
-
-
-#### **5. Show more than one operation**
-
-Chances are good that your API has more than one operation that you’ll want to document. Each OpenAPI block shows one API operation. In order to show multiple API operations, you can create an extra OpenAPI block per operation, backed by the same OpenAPI specification file.
-
-### Updating your Specification
-
-From time to time you might need to update or modify your API specification. In GitBook, you can replace the specification underlying your OpenAPI blocks, and have the update be reflected across all your documentation.
-
-#### Replacing a specification in a file
-
-1. Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"
-2. On your OpenAPI file in the file list, click "Replace"
-
-Once the OpenAPI Source has been replaced, each OpenAPI block that references your file will be updated based on your new specification.
-
-#### Replacing a specification from a link
-
-
-
-1. Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"
-2. Provide a new URL in the input box, and save
-
-Once the OpenAPI Source has been replaced, each OpenAPI block that references your file will be updated based on your new specification.
-
-### Creating an API Operation from scratch
-
-GitBook supports creating API methods from scratch, using the editable "API Method" Block. To use the "API Method" block, create a new block using the command palette, and select "API Method". Each field in the block is editable, and displays just like an OpenAPI block.
-
-
-
-With the API block, you can:
-
-- Set the URL and the path of your operation
-- Name your operation and give it a longer description or summary
-- Add, remove, and reorder **parameters**, grouped into **Path**, **Query**, **Header**, **Cookie** and **Body**
-- Add, remove, and reorder **responses**
- - Document your responses with code examples
diff --git a/content-creation/blocks/ordered-list.md b/content-creation/blocks/ordered-list.md
deleted file mode 100644
index 2aa6551d..00000000
--- a/content-creation/blocks/ordered-list.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-description: Ordered list content block
----
-
-# Ordered list
-
-Ordered or 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 `shift` + `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
-```
diff --git a/content-creation/blocks/page-link.md b/content-creation/blocks/page-link.md
deleted file mode 100644
index 96dc4d0b..00000000
--- a/content-creation/blocks/page-link.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: Page link content block
----
-
-# Page link
-
-A page link is the best way to create relations between different pages.
-
-### Example of page link block
-
-The links below point to [blocks](./) and [inline content](../editor/inline.md):
-
-{% content-ref url="./" %}
-[.](./)
-{% endcontent-ref %}
-
-{% content-ref url="../editor/inline.md" %}
-[inline.md](../editor/inline.md)
-{% endcontent-ref %}
-
-## Representation in Markdown
-
-```
-{% raw %}
-{% content-ref url="./" %} . {% endcontent-ref %}
-{% endraw %}
-```
diff --git a/content-creation/blocks/paragraph.md b/content-creation/blocks/paragraph.md
deleted file mode 100644
index be0a651b..00000000
--- a/content-creation/blocks/paragraph.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-description: Paragraph content block
----
-
-# Paragraph
-
-A paragraph is the most basic content block you can use on GitBook. It’s exactly what it says, a paragraph of text.
-
-### 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
-
-{% 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 %}
diff --git a/content-creation/blocks/quote.md b/content-creation/blocks/quote.md
deleted file mode 100644
index 7df8ee45..00000000
--- a/content-creation/blocks/quote.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-description: Quote or blockquote content block
----
-
-# Quote
-
-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 [command palette](./#command-palette) to insert it.
-
-### 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 %}
diff --git a/content-creation/blocks/table.md b/content-creation/blocks/table.md
deleted file mode 100644
index 6766130b..00000000
--- a/content-creation/blocks/table.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-description: Table content block
----
-
-# Table
-
-You can add tables to better organize your information.
-
-### Example of a table
-
-
-
-{% hint style="info" %}
-You can now convert table blocks to full width by clicking on the next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-Table columns can have the following data types, which apply restrictions or embellishments to every cell in the column:
-
-- **Text**: standard text. Can be formatted.
-- **Number:** a number, with or without floating digits.
-- **Checkbox:** a checkbox that can be checked or unchecked.
-- **Select:** data can be selected from a pre-defined list of options. Can be single-choice or multiple-choice.
-- **Users:** data can be selected from a list of the organization’s members. Can be single-choice or multiple-choice.
-- **Files:** data is a reference to a file in the space. New files can be uploaded when populating cells in the column.
-- **Rating:** A star rating, with a configurable maximum.
-
-### Changing a column type
-
-You can use the column dropdown menu to change a column’s type. Select the new type and click **save**. You’ll be prompted to confirm this change, as column data could be deleted or malformed by this action.
-
-### Resizing columns
-
-You can drag from a column’s edge to resize it. Column resizing is stored as a percentage of the overall width, which allows for relative sizing based on the overall width of the table.
-
-### Scrolling tables
-
-Tables that are wider than the editor container will be horizontally scrollable.
-
-{% hint style="info" %}
-You can drag and drop columns and rows to reorder them, and delete columns or rows using their respective context menus.
-{% endhint %}
-
-### Representation in Markdown
-
-```
-# Table
-
-| | | |
-| - | - | - |
-| | | |
-| | | |
-| | | |
-```
diff --git a/content-creation/blocks/tabs.md b/content-creation/blocks/tabs.md
deleted file mode 100644
index 0c75a2d4..00000000
--- a/content-creation/blocks/tabs.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-description: Tabs content block
----
-
-# Tabs
-
-Using tabs can be a good way to structure your content.
-
-### Example
-
-Here is an example that lists instructions relevant to specific platforms:
-
-{% tabs %}
-{% tab title="Windows" %}
-Here are the instructions for Windows
-{% endtab %}
-
-{% tab title="OSX" %}
-Here are the instructions for macOS
-{% endtab %}
-
-{% tab title="Linux" %}
-Here are the instructions for Linux
-{% endtab %}
-{% endtabs %}
diff --git a/content-creation/blocks/task-list.md b/content-creation/blocks/task-list.md
deleted file mode 100644
index e16b241e..00000000
--- a/content-creation/blocks/task-list.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: Task list content block
----
-
-# Task list
-
-Task lists allow you to create a list of items with checkboxes that you can check or uncheck. This is useful for tracking project items, shopping lists, creating playbooks and more.
-
-### Example of a task list
-
-- [ ] 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`.
-
-### 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, unidented using `shift` + `tab`.
-```
-
-{% hint style="info" %}
-Please note that readers of your published space will not be able to check or uncheck these boxes. You decide which boxes are checked and unchecked when you write the content.
-{% endhint %}
diff --git a/content-creation/blocks/unordered-list.md b/content-creation/blocks/unordered-list.md
deleted file mode 100644
index f55f86b1..00000000
--- a/content-creation/blocks/unordered-list.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-description: Unordered list content block
----
-
-# Unordered list
-
-Unordered lists are great for making a series of points that do not necessarily need to be made in a particular order.
-
-### 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 `shift` + `tab` to outdent.
-{% endhint %}
-
-### Representation in Markdown
-
-```markdown
-- Item
- - Nested item
- - Another nested item
- - Yet another nested item
-- Another item
-- Yet another item
-```
diff --git a/content-creation/content-creation-faq.md b/content-creation/content-creation-faq.md
deleted file mode 100644
index 3087bcad..00000000
--- a/content-creation/content-creation-faq.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Content creation FAQ
-
-## What browsers are supported by GitBook?
-
-GitBook supports the current versions of [Chrome](https://www.google.com/chrome/), [Firefox](http://www.mozilla.org/firefox/), [Safari](http://www.apple.com/safari/), and [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge).
-
-## Does GitBook support RTL languages?
-
-We have RTL support in mind, but it’s not yet ready. For now, only paragraphs and headings will automatically detect RTL text and adapt its layout. Lists and other content blocks are not aligned properly. Also, you may have noticed a poor font quality being used for your language.
-
-## Is there a limit on the documentation import size?
-
-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.**
-
-## **How can I export my content?**
-
-We recommend exporting your content in Markdown format by enabling [GitHub or GitLab sync](../integrations/git-sync/). You can also export your content via PDF but you may hit some limits in case of larger spaces.
-
-## Can I move a page from one space to another?
-
-We do not support moving single pages between spaces at this time. We recommend you copy and paste the content as needed. In cases of larger content reorganization where you will need to move a number of pages between spaces, we recommend you contact our support team who can guide you through moving your content via GitHub or GitLab sync.
-
-## Can I move a space between organizations?
-
-Yes, you can! [Read more about how to move a space. ](content-structure/what-is-a-space.md#move-a-space)
-
-## How do I revert to the previous version of my content?
-
-Admins and creators can click the **rollback** button while viewing a specific history item to[ roll the space back ](activity-history.md#rolling-back-to-a-previous-version)to this point in time.
-
-## Do you support offline contributions?
-
-Not at the moment!
-
-## Do you have a mobile or a desktop app?
-
-No, sorry.
diff --git a/content-creation/content-structure/README.md b/content-creation/content-structure/README.md
deleted file mode 100644
index 39b0166d..00000000
--- a/content-creation/content-structure/README.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-description: Learn how to use pages, page groups, spaces and collections.
----
-
-# Content structure
-
-Build the structure for your documentation using pages, spaces and collections. Pages live inside of spaces, and collections are groups of spaces.
-
-{% hint style="info" %}
-**Permissions**
-
-Anyone with editor permission and higher can create pages. Creators and above can create new spaces and collections.
-{% endhint %}
-
-### Learn more about:
-
-
diff --git a/content-creation/content-structure/content-in-a-space.md b/content-creation/content-structure/content-in-a-space.md
deleted file mode 100644
index fac6a960..00000000
--- a/content-creation/content-structure/content-in-a-space.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# Content in a space
-
-## Table of Contents
-
-
-
-
The table of contents in a GitBook space
-
-
-
-Each space can contain as many pages as you need to write your documentation. All these pages are visible on the left side of your screen in the **table of contents**.
-
-From the table of contents you can:
-
-- Create new [pages](content-in-a-space.md#pages)
-- Create and manage [page groups](content-in-a-space.md#groups)
-- Add [external links](content-in-a-space.md#external-links)
-- [Import external docs](../import.md) like websites or Markdown files
-
-## Organizing your content
-
-
-
-
Pages organized in the table of contents under page groups
-
-
-
-There are 4 different types of entries for the table of contents.
-
-
-
-Initial Page
-
-The initial page is the homepage or the root of your documentation and works as the main node of all the pages of your documentation.
-
-
-
-
-
-Pages
-
-A page has a title, an optional description, and a content area where you can write and add any kind of content.
-
-You can nest pages by dragging and dropping a page below an other in the table of contents.
-
-Theoretically, there is no limit to page nesting. But we advise that you avoid adding more than 3 levels of nesting to avoid overly complex structures that might be overwhelming to navigate.
-
-When you change the title of a page, the page’s **slug** (the part at the very end of the URL, e.g. `/hello-world`) will automatically update, unless you’ve already manually set the page’s slug.
-
-You can change the title and the slug of a page anytime by clicking on the triple dot icon next to the page title in the table of contents, and then clicking **rename**.
-
-
-
-
-
-Page Groups
-
-Page groups are created to bring pages together and for you to create sections of pages dealing with similar subjects.
-
-Groups can only live at the **top level of the table of contents**. You cannot nest groups inside groups.
-
-You can change the title and the slug of a group page anytime by clicking on the triple dot icon next to the group title in the table of content, and then clicking **rename**.
-
-
-
-
-
-External links
-
-These entries are external links and do not have any content in the editor. Their main function is to link to external sites or resources.
-
-
-
-## Create a new page
-
-If you’re in [live edit](../../collaboration/collaboration/live-edits.md) mode, you’ll spot the new page link on the left-hand side under the existing pages in your table of contents. If your space is locked for live edits, you’ll first need to start a new [change request](../../collaboration/collaboration/change-requests.md) by clicking the **edit** button near the top right corner of the space.
-
-
-
-
Adding a new page in a change request
-
-
-
-Once a new page is created you will be able to write rich text and rich content using our [editor](../editor/).
-
-## Create a page group
-
-If you’re in live edit mode, can click the **new page** button on the left-hand side under the existing pages in your [table of contents](https://docs.gitbook.com/getting-started/overview#table-of-contents), and then choose **new group**.
-
-
-
-
-
-
-
-## Create external links
-
-If you’re in live edit mode, can click the **new page** button on the left-hand side under the existing pages in your table of content, and then choose **new link**.
-
-
-
-
-
-
-
-## Can’t see the option to create a new page?
-
-{% hint style="warning" %}
-If [live edits](../../collaboration/collaboration/live-edits.md) are disabled for your space, you will need to create a new (or edit an existing) [change request](../../collaboration/collaboration/change-requests.md). Once you are in a change request, the **new page** button (which allows you to create pages, page groups and links) will be available.
-{% endhint %}
diff --git a/content-creation/content-structure/what-is-a-collection.md b/content-creation/content-structure/what-is-a-collection.md
deleted file mode 100644
index 19c8a87d..00000000
--- a/content-creation/content-structure/what-is-a-collection.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# What is a collection?
-
-Collections are groups of spaces focused around a specific topic, team or purpose. You can think of them as a folder for your spaces.
-
-#### Aside from organizing your content, some of the key features of collections are:
-
-* The ability to manage permissions of spaces at scale allowing you to override the organization-level defaults (read more about that in [permissions](../../account-management/member-management/permissions-and-inheritance.md)).
-* The ability to customize your collection and publish the spaces within it as variants (read more about that in [collection publishing](../../publishing/share/collection-publishing.md)).
-
-
-
-
A collection in GitBook
-
-
-
-## Create a collection
-
-You can create a collection directly in the sidebar:
-
-
-
-
Create a new collection from the sidebar
-
-
-
-Or, in the collection view, by clicking the **new collection** button:
-
-
-
-
New collection button in the collection view
-
-
-
-## Move a collection
-
-Hover over the collection name in the sidebar, then click on the triple dot icon that appears on its right-hand side. Click **move to...** from this menu and then choose its new location.
-
-## Nest collections
-
-Collections can be nested inside each other, creating a collection -> sub-collection -> space hierarchy.
-
-Hover over the collection name in the sidebar, then click on the triple dot icon that appears on its right-hand side. Click **move to...** from this menu and then choose its new location. Alternatively, you can drag and drop the collection to its new location.
-
-{% hint style="info" %}
-When you publish the primary collection, any nested collection does not show up as a variant.
-{% endhint %}
-
-## Delete a collection
-
-Hover over the collection name in the sidebar, then click on the triple dot icon that appears on its right-hand side. Click **delete** from this menu to delete the collection.
-
-{% hint style="info" %}
-**Deleting a collection is final**, but spaces inside a deleted collection will be moved to 'Trash' and can be restored up to 7 days after deletion.
-{% endhint %}
diff --git a/content-creation/content-structure/what-is-a-space.md b/content-creation/content-structure/what-is-a-space.md
deleted file mode 100644
index ad056732..00000000
--- a/content-creation/content-structure/what-is-a-space.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-description: Learn about spaces in GitBook
----
-
-# What is a space?
-
-In GitBook, a space is a project where you can start organizing your ideas. Imagine it as a virtual book where you can start writing pages individually or collaborate asynchronously with your team members.
-
-
-
-
A space in GitBook
-
-
-
-## Create a space
-
-To create a space click on the :heavy_plus_sign: button at the bottom of the sidebar.
-
-You can also create a space directly from your organization library or a collection screen using the **new space** button:
-
-
-
-
Create a new space from the collection screen
-
-
-
-Each new space can be a **private space** or a **team space**. Private spaces are useful for notes you take personally that don’t need to be shared with the rest of your team.
-
-
-
-
You can choose between creating a private space or a team space
-
-
-
-{% hint style="info" %}
-Please note that private spaces can’t be moved to your team’s shared spaces. Everything created as a private space will remain accessible only to you.
-{% endhint %}
-
-## Duplicate a space
-
-
-
-
Duplicating a space
-
-
-
-To duplicate a space, select **duplicate** from the space’s menu.
-
-Duplicating a space will create a copy of the source space, in the same location (organization, collection, sub-collection, etc.) as the source space.
-
-For example, duplicating a space called **Design System**, that lives in the Design collection, will be saved as **Copy of Design System**, inside the Design collection. Once duplicated you can edit the name as required.
-
-## Move a space
-
-To move a space navigate to the space name in the sidebar, open the triple dot menu, click on **move space to...** and then decide where to move it. Alternatively, simply drag and drop a space in the sidebar to reorder it.\
-\
-You can move spaces between collections or even organizations, if you have an [admin role](../../account-management/member-management/roles.md) in both.
-
-
-
-
Moving a space
-
-
-
-{% hint style="info" %}
-Similar to private spaces, team spaces can’t be moved to your private section.
-{% endhint %}
-
-## Delete a space
-
-You can delete your space from the space page by clicking the triple dot menu in the top right corner and clicking **delete**. You will need to confirm the deletion in a popup.
-
-**Deleted spaces can be restored from trash for up to 7 days**. After that time, they will be permanently deleted.
diff --git a/content-creation/editor/README.md b/content-creation/editor/README.md
deleted file mode 100644
index 83e5493a..00000000
--- a/content-creation/editor/README.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-description: >-
- GitBook’s documentation editor supports rich text, various content blocks, and
- Markdown.
----
-
-# Editor
-
-You can build your documentation with a range of editing blocks and inline content, formatting it to match your needs.
-
-{% hint style="info" %}
-**Permissions**\
-The editing function can be accessed by anyone with editor permissions or higher.
-{% endhint %}
-
-### Learn more about:
-
-
Rich text
Learn how to add relative and absolute links and other rich text.
diff --git a/content-creation/editor/formatting.md b/content-creation/editor/formatting.md
deleted file mode 100644
index 60acb1ca..00000000
--- a/content-creation/editor/formatting.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-description: Formatting and styling inline content
----
-
-# Formatting
-
-You can format your text selecting it and choosing one of the options that pop up:
-
-
-
-
Formatting options
-
-
-
-{% hint style="info" %}
-Hovering over the formatting options displays a tip with the markdown markup you can use to achieve the same formatting, as well as a keyboard shortcut you can use to do the same.
-
-
-{% endhint %}
-
-### Bold
-
-Keyboard shortcut: `Command + B`
-
-{% hint style="info" %}
-**Command** is the macOS key. Use **Windows** on Windows and **Control** on Linux.
-{% endhint %}
-
-{% tabs %}
-{% tab title="Markdown" %}
-```markdown
-**Bold**
-```
-{% endtab %}
-{% endtabs %}
-
-### Italic
-
-Keyboard shortcut: `Command + I`
-
-{% tabs %}
-{% tab title="Markdown" %}
-```markdown
-_Italic_
-```
-{% endtab %}
-{% endtabs %}
-
-### Strikethrough
-
-Keyboard shortcut: `Command + Shift + S`
-
-{% tabs %}
-{% tab title="Markdown" %}
-```markdown
-~~Strikethrough~~
-```
-{% endtab %}
-{% endtabs %}
-
-### Code
-
-Keyboard shortcut: `Command + E`
-
-{% tabs %}
-{% tab title="Markdown" %}
-```markdown
-`Code`
-```
-{% endtab %}
-{% endtabs %}
-
-### Link
-
-Keyboard shortcut: `Command + K`
-
-This is [a link to an external page](https://www.gitbook.com).
-
-This is [a link to a page in this space](broken-reference/).
-
-This is [a link to a section on this page](formatting.md#color).
-
-This is [a link that starts an email to a specific address](mailto:support@gitbook.com).
-
-### Color
-
-Keyboard shortcut: `Command + K`
diff --git a/content-creation/editor/inline.md b/content-creation/editor/inline.md
deleted file mode 100644
index 3f9f2cf1..00000000
--- a/content-creation/editor/inline.md
+++ /dev/null
@@ -1,108 +0,0 @@
----
-description: Space inline content
----
-
-# Inline content
-
-You can choose to insert inline content using the inline palette. This palette becomes available when you type a forward slash. The forward slash will be replaced by the inline content you choose to insert.
-
-
-
-
Inline palette
-
-
-
-## Annotations
-
-Annotations allow you to add more context to your text without breaking the reader’s train of thought.
-
-### Example of an annotation
-
-
-
-
Example of an annotation
-
-
-
-### How to create an annotation
-
-To create an annotation select the word or phrase you would like to annotate. Once you have selected the text, write the annotation, then click out of it to continue writing in your main paragraph.
-
-### Git Sync representation in Markdown
-
-Markdown footnotes will be imported as annotations
-
-## Images
-
-You can insert inline images to your content. By default, their size is proportional to the font size as their main purpose is to be inserted in line with your content. This is great for badges and icons.
-
-There are 3 different sizes of inline images:
-
-1. **Inline size:** the default one is proportionally sized to the font.
-2. **Original size:** will remain inline but with its original size with a maximum width.
-3. **Convert to block:** this turns an inline image into a [block image](../blocks/insert-images.md) with its original size.
-
-{% hint style="info" %}
-You can switch the size of an inline image by clicking on the image to open the formatting palette, and then choosing one of the options above.
-{% endhint %}
-
-## Emojis
-
-You can add emoji by opening the **inline palette**. Alternatively, type `:` and a list of emojis will pop up directly in line.
-
-## Links
-
-You can insert three different types of links:
-
-- [Relative links](inline.md#relative-links)
-- [Absolute links](inline.md#absolute-links)
-- [Email address `mailto` links](inline.md#email-addresses)
-
-## Relative links
-
-Relative links are links created by linking pages that already exist in your content. 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 resulting in fewer broken links.
-
-Here’s how to insert a relative link:
-
-1. Select some text or click somewhere in your paragraph where you want to insert the link.
-2. Wait for the inline palette to appear.
-3. Click the inline palette.
-4. Start typing the page title.
-5. Select the page from the drop-down search results.
-6. Hit `enter`.
-
-## Absolute links
-
-Absolute links are for external links.
-
-{% hint style="info" %}
-External links will always open in a new tab.
-{% endhint %}
-
-Here’s how to insert an absolute link:
-
-1. Select some text or click somewhere in your paragraph where you want to insert the link.
-2. Wait for the inline palette to appear.
-3. Click the inline palette.
-4. Paste a URL.
-5. Hit `enter`.
-
-## 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, fill in `TO` with the email address of your link, and allow them to write an email to send out.
-
-Here’s how to insert an email address `mailto` link:
-
-1. Select some text or click somewhere in your paragraph where you want to insert the link.
-2. Wait for the inline palette to appear.
-3. Click the inline palette.
-4. Paste or type `mailto:something@address.com`, replacing `something@address.com` with the email address you would like to use.
-5. Hit `enter`.
-
-## Math & TeX
-
-You can create an inline math formula like this: $$f(x) = x * e^{2 pi i \xi x}$$
-
-{% hint style="info" %}
-You can also insert a block-level math formula directly from the [**command palette**](../blocks/#math-equation).
-{% endhint %}
diff --git a/content-creation/editor/markdown.md b/content-creation/editor/markdown.md
deleted file mode 100644
index d9ecffa4..00000000
--- a/content-creation/editor/markdown.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Markdown
-
-The editor allows you to include formatted text using rich text, as well as markdown.
-
-Markdown is a popular markup syntax that’s widely known for its simplicity and popularity online. 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
-
-We support all the classic inline Markdown formatting:
-
-| Formatting | Markdown version | Result |
-| ------------- | ----------------- | ----------------- |
-| Bold | `**bold**` | **text** |
-| Italic | `_italic_` | _italic_ |
-| Strikethrough | `~strikethrough~` | ~~strikethrough~~ |
-
-## 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.
-
-{% hint style="info" %}
-We use [Prism](https://github.com/PrismJS/prism) for syntax highlighting. Here’s an easy way to check which languages Prism supports: [Test Drive Prism](https://prismjs.com/test.html#language=markup). If you notice a mismatch between GitBook and Prism, there’s a chance we are a version or two behind. We’ll catch up soon!
-{% endhint %}
-
-## Lists
-
-We automatically detect ordered and unordered lists as you type.
-
-- Begin a line with `-` or `*` to start a bullet list.
-- Being a line with `1.` to start a numbered list. Use `Tab` to go one level deeper, and `Shift+Tab` to go up.
-- Begin a line with `- [ ]` to start a task list.
-
-## 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
diff --git a/content-creation/editor/rich-text.md b/content-creation/editor/rich-text.md
deleted file mode 100644
index 55dd950b..00000000
--- a/content-creation/editor/rich-text.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Rich text
-
-## Text formatting
-
-You can add some formatting by selecting some text to open the **inline palette**. ✨
-
-{% hint style="info" %}
-When hovering over one of the formatting options you can see the [Markdown alternatives](markdown.md) and [keyboard shortcuts](../../product-tour/keyboard-shortcuts.md).
-{% endhint %}
-
-## Links
-
-You can add links to your content in 2 different ways:
-
-### Relative links
-
-Relative links are links created by linking pages already existing in your content. 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 resulting in fewer broken links.
-
-
-
-### Absolute links
-
-Absolute links are for external links. Select some text to open the **inline palette**, then click on 🔗 , paste a URL and press **enter**.
-
-
-
-### Email address
-
-You can also add an email address using the inline palette. Just write `mailto:something@adress.com` and click **enter**.
diff --git a/content-creation/import.md b/content-creation/import.md
deleted file mode 100644
index e1c4271e..00000000
--- a/content-creation/import.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-description: >-
- Find out how to easily migrate your existing documentation and which formats
- are supported.
----
-
-# Import
-
-The import function allows you to migrate and unify existing documentation in GitBook. You can choose to import single or multiple pages although limits apply.
-
-{% hint style="info" %}
-**Permissions**
-
-All members with editor permission or above can use the import feature.
-{% endhint %}
-
-## Supported formats
-
-GitBook supports imports from websites or files that are:
-
-- Markdown (.md or .markdown)
-- HTML (.html)
-- Microsoft Word (.docx).
-
-We also support import from:
-
-- Confluence
-- Notion
-- GitHub Wiki
-- Quip
-- Dropbox Paper
-- Google Docs
-
-You can also upload a ZIP containing HTML or Markdown files when **importing multiple pages.**
-
-{% hint style="warning" %}
-**Note: this feature is in beta.**
-
-Feel free to suggest import sources we don’t support yet and [let us know](../help/support.md) if you have any issues.
-{% endhint %}
-
-## Import panel
-
-When you create a new space, you’ll have the option to import content straight away:
-
-
-
-
The new page menu
-
-
-
-Import a page or subpage by selecting `Import Page` from the New Page menu, or `Import Subpage` in the page action menu, found in the table of contents:
-
-
-
-
Import from the page action menu
-
-
-
-When you choose your input source, instructions will explain how to proceed.
-
-{% hint style="warning" %}
-Although GitBook supports importing content from different kinds of sources, the end result might be different from your source due to differences in product features and document format.
-{% endhint %}
-
-## Limits
-
-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.**
diff --git a/content-editor/activity-history.md b/content-editor/activity-history.md
deleted file mode 100644
index 79c4f628..00000000
--- a/content-editor/activity-history.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-icon: rectangle-vertical-history
-description: Keep track of changes, roll back to a previous version, and more.
----
-
-# Version control
-
-You can easily monitor all the changes people have made to your content using to the **Version history** side panel.
-
-### Version history
-
-In the Version history of a space, you can see a list of all the actions that changed the content within it. These include:
-
-* When someone made [live edits](editing-content/live-edits.md) to the space.
-* When someone merged a [change request](../collaboration/change-requests.md).
-* When someone performed a [Git Sync](../integrations/git-sync/) operation.
-
-### Viewing historical versions of content
-
-To view past versions of your content and see the changes that were made, click the **Version history** button from the space’s **Actions menu** in the top-right corner.
-
-{% hint style="info" %}
-**Permissions:** Only users with **admin**, **creator**, **reviewer** and **editor** permissions can view the version history for a space.
-{% endhint %}
-
-Click on any item in the list to see how your content looked at the point this change was made. This is very similar to how you view [change requests](../collaboration/change-requests.md).
-
-
The Version history side panel shows all the historical changes people have made to a space.
-
-### Show changes
-
-When you are viewing an old version of your content, you can choose to highlight the differences between the old and current content — similar to [diff view in a change request](../collaboration/change-requests.md#diff-mode).
-
-To enable or disable this, use the **Show changes** toggle at the bottom of the **Version history** side panel.
-
-With show changes enabled, content that has changed will be highlighted by an icon on the left of its content block.
-
-### Viewing historical published versions
-
-If you're investigating the version history of a published space, you can also view previews of what the previous versions looked like in the published context (i.e. what the end user would see).
-
-You can do this by:
-
-{% stepper %}
-{% step %}
-From the version history side panel, select the revision
-{% endstep %}
-
-{% step %}
-Copy the ID at the end of the URL
-{% endstep %}
-
-{% step %}
-Add it at the end of your published docs URL as `/~/revisions/`
-{% endstep %}
-{% endstepper %}
-
-### Rolling back to a previous version
-
-Rolling back allows you to revert a space’s content to the way it was at a previous point in time. This is helpful if you’ve accidentally made a breaking change or deleted content and need to quickly get back to a previous version of the space.
-
-To roll back to a previous version of your space, hover over the version in the side panel, click the **Actions button** and select **Rollback**.
-
-{% hint style="info" %}
-**Permissions:** Only users with **admin**, **creator** and **reviewer** permissions can roll back to a previous version.
-{% endhint %}
diff --git a/content-editor/blocks/README.md b/content-editor/blocks/README.md
deleted file mode 100644
index 27fef859..00000000
--- a/content-editor/blocks/README.md
+++ /dev/null
@@ -1,60 +0,0 @@
----
-icon: square-dashed-circle-plus
-description: "How to add and edit blocks within your content —\_plus a full list of the standard blocks GitBook offers."
----
-
-# Blocks
-
-GitBook is a block-based editor, meaning you can add all 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.
-
-### 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`.
-
-
You can open the insert palette using the + button to the left of your content, or by typing / on an empty block.
-
-### 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](hint.md), 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**.
-
-### Full-width blocks
-
-By making your blocks full width, you can create a clear visual hierarchy in your content, or simply give more space to content that needs it.
-
-To make a block full width, click on the **Options menu** next to your block and select **Full width**. This feature is available for the following block types:
-
-* Code Blocks
-* Image blocks
-* Tables
-* Cards
-* API Blocks
-* Integration blocks
-
-#### Example of a full-width table block
-
-
-
diff --git a/content-editor/blocks/cards.md b/content-editor/blocks/cards.md
deleted file mode 100644
index 48458543..00000000
--- a/content-editor/blocks/cards.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-description: "Display information more dynamically with a set of cards —\_with or without images."
----
-
-# Cards
-
-You can use cards to create a visually pleasing page layout, combining text and images in a grid. They’re ideal for building landing pages or displaying any other content in a non-linear way.
-
-You can adjust [switch between medium or large cards](cards.md#card-size) and link them to the relevant resources — read on to find out more.
-
-### Example of a card
-
-
GitBook homepage
Visit our website and find out more about GitBook.
-
-### Adding links
-
-Hover over a card and open its **Options menu** . Here you can add a target link, so users can jump directly to a location when they click the card.
-
-{% hint style="success" %}
-When creating cards, we recommend you use **target links instead of hyperlinks**. With a target link, your readers can click anywhere on the card to access the linked URL.
-{% endhint %}
-
-### Adding images
-
-Hover over a card and open its **Options menu** . Here you can add a cover image to your card.
-
-Clicking **Add cover** will open the [Select image side panel](insert-images.md#how-to-add-images) — you can drag and drop a new image into this, or use an image file you’ve previously uploaded to your space.
-
-The key to great looking cards is making sure all the images in a card block have the same ratio. For example:
-
-* 16:9 (eg. 1920px x 1080px)
-* 4:3 (eg. 1024px x 768px)
-* 1:1 (eg. 500px x 500px)
-
-By using images with the same ratio, all your cards will perfectly align on the page. This means that titles and text below your images will also stay aligned, for a great reading experience.
-
-#### Card size
-
-You can select the card size by opening the **Options menu** to the left of your card block. The **Medium** option creates three cards in one horizontal line, while the **Large** option shows two larger cards on each line.
-
-{% hint style="info" %}
-You can make card blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
-{% endhint %}
diff --git a/content-editor/blocks/code-block.md b/content-editor/blocks/code-block.md
deleted file mode 100644
index a059886b..00000000
--- a/content-editor/blocks/code-block.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-description: >-
- Add a code block to a page to include sample code, configurations, code
- snippets and more.
----
-
-# Code blocks
-
-You can add code to your GitBook pages using code blocks.
-
-When you add a code block, you can choose to [set the syntax](code-block.md#set-syntax...), [show line numbers](code-block.md#with-line-numbers), [show a caption](code-block.md#with-caption), and [wrap the lines](code-block.md#wrap-code). It’s also easy to [copy the contents of a code block to the clipboard](code-block.md#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!
-
-### 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](tabs.md) 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 %}
-
-{% hint style="info" %}
-You can make code blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
-{% endhint %}
-
-### 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 %}
-
-```
-// Some code
-```
-
-#### 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](code-block.md#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.
-
-### 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 in one click.
-
-
Click here to copy the contents of a code block to your clipboard, ready for you to paste elsewhere.
-
-### Representation in Markdown
-
-````markdown
-{% raw %}
-{% 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 %}
-{% endraw %}
-````
diff --git a/content-editor/blocks/drawing.md b/content-editor/blocks/drawing.md
deleted file mode 100644
index e83c010a..00000000
--- a/content-editor/blocks/drawing.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: "Create drawings within GitBook and add them to your page —\_perfect for diagramming and sketching out quick ideas."
----
-
-# Drawings
-
-You can create a drawing or sketch directly though GitBook using the integrated [Excalidraw](https://excalidraw.com/) editor, then add it right into your GitBook page.
-
-To create a drawing, press `/` on an empty line to bring up the insert palette and choose **Drawing**. This will open a popover with Excalidraw tools — simply close the popover when you’re done and your diagram will appear on your GitBook page.
-
-GitBook stores drawings as special SVG files in the space. Those files have an extension of `drawing.svg`.
-
-### Example of a drawing block
-
-
-
-### Draw with GitBook AI
-
-{% hint style="warning" %}
-GitBook AI is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-When using drawing block, you can ask GitBook AI to generate an illustration by specifying a prompt. Simply type in a prompt and hit **Generate**, or choose one of the suggested prompts to get started.
-
-Once GitBook AI has finished the drawing, you can double-click to open the full drawing palette and edit it however you like.
-
-When editing a drawing, click the **Use AI to generate** button to bring up GitBook AI’s prompt editor again and generate a new drawing.
diff --git a/content-editor/blocks/embed-a-url.md b/content-editor/blocks/embed-a-url.md
deleted file mode 100644
index c6223fbc..00000000
--- a/content-editor/blocks/embed-a-url.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-description: "Embed content directly into your page with a URL —\_including videos, music and interactive blocks."
----
-
-# Embedded URLs
-
-To add an embedbed URL, simply paste the link of the content you want to embed and hit `Enter`!
-
-{% hint style="info" %}
-**Note:** The content you want to embed must be publicly available in order for GitBook to access the file. For example, when embedding a Google doc the share settings must be set to _Anyone with the link_.
-{% endhint %}
-
-Here are a few examples of the kind of content you can embed into GitBook — and there are many more!
-
-### Videos
-
-{% hint style="info" %}
-**Note:** You can choose to auto-play and loop videos that you embed into GitBook by adding `?autoplay=1&_loop=1` to the end of your video’s URL
-{% endhint %}
-
-{% embed url="https://www.youtube.com/watch?v=D_uLM5i0Z4c" %}
-
-### Codepen
-
-{% embed url="https://codepen.io/davidkpiano/pen/wMqXea" %}
-
-### Spotify
-
-{% embed url="https://open.spotify.com/track/4FmiciU3ZmfgABlbCSXcWw?si=65zMAhStT2ivTit-kZISWg" %}
-
-### Representation in Markdown
-
-```markdown
-{% raw %}
-{% embed url="URL_HERE" %}
-{% endraw %}
-```
diff --git a/content-editor/blocks/heading.md b/content-editor/blocks/heading.md
deleted file mode 100644
index cff4c5d8..00000000
--- a/content-editor/blocks/heading.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-description: Add heading blocks to a page to organize your content and improve SEO.
----
-
-# Headings
-
-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](../editor/navigation.md#page-outline).
-
-{% hint style="info" %}
-Reading on a screen is less comfortable than reading on paper. Sometimes splitting longer content into different [pages](../editor/content-structure/content-in-a-space.md) can help with overall readability.
-{% endhint %}
-
-### 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 GitBook space, you can use a [relative link](../editing-content/inline.md#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.
-
-### Heading examples
-
-## My heading 1
-
-### My heading 2
-
-#### My heading 3
-
-### Representation in Markdown
-
-{% code overflow="wrap" %}
-```markdown
-# My heading 1
-## My heading 2
-### My heading 3
-```
-{% endcode %}
diff --git a/content-editor/blocks/hint.md b/content-editor/blocks/hint.md
deleted file mode 100644
index d20f1660..00000000
--- a/content-editor/blocks/hint.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-description: >-
- Add a hint to a page to draw your reader’s attention to specific pieces of
- important information.
----
-
-# Hints
-
-Hints 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 clicking the colored icon, or by opening the block’s **Options menu** and selecting the style you want.
-
-Hint blocks support [inline content](../editing-content/inline.md) and [formatting](../editing-content/formatting.md), 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](./#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" %}
-### 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 %}
-
-### Representation in Markdown
-
-```markdown
-{% raw %}
-{% 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" %}
-
-## 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 %}
-{% endraw %}
-```
diff --git a/content-editor/blocks/insert-files.md b/content-editor/blocks/insert-files.md
deleted file mode 100644
index 18af6c98..00000000
--- a/content-editor/blocks/insert-files.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-description: "Add a PDF, OpenAPI file and more to your page —\_plus learn how to manage all your files in GitBook."
----
-
-# Files
-
-You can upload files to your GitBook space 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 file
-
-{% file src="../../.gitbook/assets/hello-world.pdf" %}
-This is a caption on a file.
-{% endfile %}
-
-## Uploading a file
-
-You can manage uploaded files in the Files side panel of your space. To access the Files panel, click on **Files** in the [space sub-navigation](../editor/navigation.md#space-header-and-sub-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 your space when you add an [image block](insert-images.md) or an [OpenAPI block](openapi/). When you create one of these blocks, the Files panel will open, 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 Files side panel for the respective space, so you can view and manage them later.
-{% endhint %}
-
-## Managing files
-
-In the **Files** side panel, you can search for, rename, or delete files in your current space. You can see all your uploaded files below the search bar and file upload sections.
-
-Each file has an **Actions menu** that lets you download, replace, rename, or delete your file. You can search for file names using the search box. Above that you’ll find a **Sort** option, which lets you sort your files by the date they were last modified, or their size.
-
-
In the Files side panel, you can upload, download, replace, edit, download and delete files.
-
-### 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 **Actions menu** for the file and click **Replace**. In the file replacement dialog that appears, select the new file and wait for the upload indicator to complete. Your file will automatically update everywhere it appeared in your space.
-
-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 space, 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 space by creating an image or a file block and selecting it from the **Files** side panel.
-
-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 %}
-
-### Related — embed external content
-
-If you want to embed external content into your pages, take a look at [how to embed a URL](embed-a-url.md).
diff --git a/content-editor/blocks/insert-images.md b/content-editor/blocks/insert-images.md
deleted file mode 100644
index f4d76b78..00000000
--- a/content-editor/blocks/insert-images.md
+++ /dev/null
@@ -1,170 +0,0 @@
----
-description: Add an image block to a page.
----
-
-# Images
-
-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 highly recommend setting alt text for every image in your space.
-{% endhint %}
-
-### Image block examples
-
-Image blocks can display a single image or a gallery on your page, like this:
-
-
-
-
-
-
-
-{% hint style="info" %}
-You can make image blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
-{% endhint %}
-
-### How to add images
-
-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](./#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 %}
-
-#### How to 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 **Actions 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 **Actions 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.
-
-
Once you’ve set an image for both light and dark mode, you can replace either from this menu.
-
-{% hint style="warning" %}
-**Note:** GitBook doesn’t currently support light and dark mode images for certain cases, including [page covers](../../published-documentation/customization/page-layouts.md#page-covers) or image covers on [cards](cards.md).
-{% 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 **Actions menu** . Click the **Size** button to change the size of your image from the available options.
-
-
-
-* **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](insert-images.md#resizing).
-
-### Representation in Markdown
-
-```markdown
-//Simple Block
-
-
-//Block with Caption
-
-
-//Block with Alt text
-
-
-
-//Block with Caption and Alt text
-
-
GitBook Logo
-
-//Block with different image for dark and light mode, with caption
-
-
-
-
-
- Caption text
-
-```
-
-### Related
-
-If you are looking to embed external content into your pages, take a look at how to [embed a URL](embed-a-url.md).
diff --git a/content-editor/blocks/math-and-tex.md b/content-editor/blocks/math-and-tex.md
deleted file mode 100644
index 0b60bc79..00000000
--- a/content-editor/blocks/math-and-tex.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-description: >-
- Add a mathTeX block to a page when you want to display a mathematical formula
- in your documentation.
----
-
-# Math & TeX
-
-You can use the mathTeX format to include mathematical formulae in your documentation. We offer this through the [KaTeX](https://katex.org/docs/supported.html) library.
-
-You can also add mathTeX [as inline content](../editing-content/inline.md#math-and-tex).
-
-### Example of Math & TeX block
-
-$$
-s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
-$$
-
-
-
-### Representation in Markdown
-
-$$f(x) = x * e^{2 pi i \xi x}$$
-
-```markdown
-# Math and TeX block
-
-$$f(x) = x * e^{2 pi i \xi x}$$
-```
diff --git a/content-editor/blocks/openapi/README.md b/content-editor/blocks/openapi/README.md
deleted file mode 100644
index abb7caaa..00000000
--- a/content-editor/blocks/openapi/README.md
+++ /dev/null
@@ -1,154 +0,0 @@
----
-description: Add an OpenAPI spec to a page.
----
-
-# OpenAPI methods
-
-You can sync with an OpenAPI or Swagger file or URL to include auto-generated methods in your documentation.
-
-### Test it (powered by Scalar)
-
-GitBook's OpenAPI block also supports a "try it" functionality, which allows your users to test your API methods with data and parameters filled in from the editor.
-
-Powered by [Scalar](https://scalar.com/), you won't need to leave the docs in order to see your API methods in action. See and example of this below.
-
-### Example of an OpenAPI block
-
-{% swagger src="https://petstore3.swagger.io/api/v3/openapi.json" path="/pet" method="post" %}
-[https://petstore3.swagger.io/api/v3/openapi.json](https://petstore3.swagger.io/api/v3/openapi.json)
-{% endswagger %}
-
-Manually writing documentation for your REST API can be time-consuming. To help, GitBook supports OpenAPI document imports, which describe your API, and provides API blocks. These will automatically represent your API methods based on the specification you provide — either as a file or as a URL for GitBook to load.
-
-GitBook supports [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) or [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) compliant files.
-
-### Options
-
-GitBook supports extra options you can define in your OpenAPI specification to alter they way your API methods display in your published documentation.
-
-| Property | Values | Description |
-| ------------------ | ----------------- | ------------------------------------------------------- |
-| `x-hideTryItPanel` | `true` \| `false` | Show or hide the "Test it" button for an OpenAPI block. |
-| `x-codeSamples` | `true` \| `false` | Show or hide code samples for an OpenAPI block. |
-
-Both properties can be set on either the root level or on a per-operation basis.
-
-**Root**
-
-```yaml
-x-hideTryItPanel: true
-x-codeSamples: false
-paths:
- /user
- get:
- summary: Get the current user
-```
-
-**Operation**
-
-```yaml
-paths:
- /user
- get:
- summary: Get the current user
- x-hideTryItPanel: true
- x-codeSamples:
- - lang: javascript
- label: JS
- source: console.log('Hello')
-```
-
-### Create OpenAPI block using your OpenAPI file
-
-Once you have an OpenAPI compliant representation of your API, you can use it in your documentation.
-
-1. **Create a new OpenAPI block using the insert palette.**
-2. **Add your OpenAPI specification, choosing between one of the following options**:
- 1. Upload your OpenAPI formatted file
- 2. Provide a URL to your publicly available OpenAPI file.
-
-If you’re providing a **URL**, make sure that the file is available on the open internet, and that it’s not behind any kind of password protection.
-
-If you’re just experimenting, you can use one of the [default Swagger files](https://petstore.swagger.io/#/):
-
-`https://petstore.swagger.io/v2/swagger.json`
-
-3. Choose your API operation
-
-To change the operation that your swagger block is showing, use the "Choose API Operation" option in the block menu
-
-4. Show more than one operation
-
-Your API is likely to have more than one operation that you'll want to document. Each OpenAPI block shows one API operation. In order to show multiple API operations, you can create an extra OpenAPI block per operation, backed by the same OpenAPI specification file.
-
-### Update your specification
-
-From time to time you might need to update or modify your API specification. In GitBook, you can replace the specification underlying your OpenAPI blocks, and have the update be reflected across all your documentation.
-
-#### Replacing a specification in a file
-
-1. Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"
-2. On your OpenAPI file in the file list, click "Replace"
-
-Once the OpenAPI Source has been replaced, each OpenAPI block that references your file will be updated based on your new specification.
-
-#### Replacing a specification from a link
-
-1. Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"
-2. Provide a new URL in the input box, and save
-
-Once the OpenAPI Source has been replaced, each OpenAPI block that references your file will be updated based on your new specification.
-
-### API method block (deprecated)
-
-{% hint style="danger" %}
-**Editable API method blocks are now deprecated**
-
-In light of our updated OpenAPI method block, **we’ve decided to deprecate the API method block.** [Read our recent announcement](https://changelog.gitbook.com/announcements/depreciating-api-method-block) to find out more about the reasons behind this change.
-
-On **Monday 4 March 2024**, we automatically transitioned all pre-existing API method blocks to regular blocks in the format you can see below. [Read our announcement](https://changelog.gitbook.com/announcements/depreciating-api-method-block) to find out more.
-{% endhint %}
-
-You can still create editable API references from the **Quickstart** section of the **Insert menu**. Hit / on your keyboard and select **API Reference**. GitBook will create an editable section that looks like this:
-
-## Create a new user
-
-`POST` `/users`
-
-\
-
-**Headers**
-
-| Name | Value |
-| ------------- | ------------------ |
-| Content-Type | `application/json` |
-| Authorization | `Bearer ` |
-
-**Body**
-
-| Name | Type | Description |
-| ------ | ------ | ---------------- |
-| `name` | string | Name of the user |
-| `age` | number | Age of the user |
-
-**Response**
-
-{% tabs %}
-{% tab title="200" %}
-```json
-{
- "id": 1,
- "name": "John",
- "age": 30
-}
-```
-{% endtab %}
-
-{% tab title="400" %}
-```json
-{
- "error": "Invalid request"
-}
-```
-{% endtab %}
-{% endtabs %}
diff --git a/content-editor/blocks/openapi/support-for-ci-cd-with-api-blocks.md b/content-editor/blocks/openapi/support-for-ci-cd-with-api-blocks.md
deleted file mode 100644
index ce5f606f..00000000
--- a/content-editor/blocks/openapi/support-for-ci-cd-with-api-blocks.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-description: How to use GitBook’s OpenAPI method blocks to support a CI/CD workflow
----
-
-# Support for CI/CD with API blocks
-
-Our OpenAPI block supports CI/CD, which means your API documentation can auto-update when a new version is released. The method of updating depends on whether you upload your API spec via URL or as a file.
-
-## URL upload
-
-If you upload your API spec via a URL, your docs will auto-update existing API references when they change in the spec. However, when the OpenAPI file is changed, the cache will not be updated immediately. It may take a few hours for the published docs to reflect the latest version, but it can take up to a day.
-
-For example, [this](https://github.com/GitbookIO/integrations/blob/main/docs/gitbook-api/reference/collections.md) is the method we use in our developer docs.
-
-## API file upload
-
-If you upload your API spec as a file, you will have to re-upload the new version of the file in order to update your documentation. However, GitBook will detect existing blocks on the same page and auto-update them when you upload the file.
-
-An alternative solution is to use Git Sync with an OpenAPI spec file in the synced repository. Store the OpenAPI spec in a repository as a JSON/YAML file and reference it in Markdown:
-
-{% code overflow="wrap" %}
-```markdown
-{% raw %}
-{% swagger src="./openapi.json" path="/collections/{collectionId}" method="get" expanded="true" %}
-[openapi.json](./openapi.json)
-{% endswagger %}
-{% endraw %}
-```
-{% endcode %}
-
-Every time this file changes and a commit is pushed to GitHub, your docs will also update. This ensures that your documentation is always up to date with your latest API changes.
diff --git a/content-editor/blocks/ordered-list.md b/content-editor/blocks/ordered-list.md
deleted file mode 100644
index 668970f7..00000000
--- a/content-editor/blocks/ordered-list.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-description: "Add an ordered list to a page to create instructions or steps —\_perfect when you need to write a guide."
----
-
-# Ordered lists
-
-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
-
-A common pattern in documentation is adding images throughout ordered lists to help guide users with screenshots or diagrams.
-
-Let's say we want to add an image below the second item in our ordered list. In order to accomplish this in GitBook, on the row below the image you would type `3.` and then hit `space`, and the ordered list would continue.
-
-1. Item 1
-2. Item 2
-
-
-
-3. Item 3
-4. Item 4
diff --git a/content-editor/blocks/page-link.md b/content-editor/blocks/page-link.md
deleted file mode 100644
index e4b16258..00000000
--- a/content-editor/blocks/page-link.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: "Add a page link block to show relations between pages in your space —\_and to highlight an important link on your page"
----
-
-# Page links
-
-Page link blocks are the best way create relations between different pages within your content. Page links stand out on the page as they fill their own block — compared to a hyperlink added to some text.
-
-### Example of page link block
-
-The links below point to [blocks](./) and [inline content](../editing-content/inline.md):
-
-{% content-ref url="./" %}
-[.](./)
-{% endcontent-ref %}
-
-{% content-ref url="../editing-content/inline.md" %}
-[inline.md](../editing-content/inline.md)
-{% endcontent-ref %}
-
-## Representation in Markdown
-
-```markdown
-{% raw %}
-{% content-ref url="./" %} . {% endcontent-ref %}
-{% endraw %}
-```
diff --git a/content-editor/blocks/paragraph.md b/content-editor/blocks/paragraph.md
deleted file mode 100644
index 2bd45385..00000000
--- a/content-editor/blocks/paragraph.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: >-
- Add a paragraph block to a page in GitBook so you can insert formatted text,
- inline images and more.
----
-
-# Paragraphs
-
-A paragraph is the most basic content block you can use on GitBook. It’s exactly what it says — a paragraph of text.
-
-{% hint style="info" %}
-You can [add other inline content](../editing-content/inline.md) to your paragraph, such as emojis, images and Math & TeX. You can also [format your paragraph text](../editing-content/formatting.md) using the context menu or keyboard shortcuts, or [using Markdown](../editing-content/markdown.md).
-{% 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 %}
diff --git a/content-editor/blocks/quote.md b/content-editor/blocks/quote.md
deleted file mode 100644
index fc9818ec..00000000
--- a/content-editor/blocks/quote.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-description: >-
- 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
-
-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](./#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 %}
diff --git a/content-editor/blocks/reusable-content-blocks-beta.md b/content-editor/blocks/reusable-content-blocks-beta.md
deleted file mode 100644
index d0a0745f..00000000
--- a/content-editor/blocks/reusable-content-blocks-beta.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-description: >-
- Turn a set of blocks into a single reusable block that you can add to multiple
- pages and update all at once
----
-
-# Reusable Content Blocks (beta)
-
-Reusable content blocks allow you to insert reusable content into your docs. See the overview page for [Reusable Content](../../reusable-content/overview.md) for more info.
-
-
-
-### **Insert reusable content**
-
-You can insert a reusable content block as you would with any other block. Hit `/` on an empty line to open the **Insert palette** and choose **Reusable Content Block**. Alternatively, click the `+` on the left of any block or empty line.
-
-You can choose the block you want to add from the list, or search for the one you need.
-
-### **Detach a reusable content block**
-
-You can detach a reusable content block by opening the **Action menu** and selecting **Detach instance**. Detaching an instance of a block will only detach it in the current page.
-
-Once detached, any changes you make to the block(s) will not be reflected across the other instances, and changes you make in those instances will not be reflected in the detached block(s).
-
diff --git a/content-editor/blocks/snippets.md b/content-editor/blocks/snippets.md
deleted file mode 100644
index 81e3cba7..00000000
--- a/content-editor/blocks/snippets.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-description: >-
- Add a snippet block to reference a specific snippet on your page, and
- highlight it as important
-hidden: true
----
-
-# Snippets
-
-Snippet blocks are a great way to reference a snippet in your content. Snippet blocks help make the link to your snippet stand out on the page compared to [an inline link](../editing-content/inline.md#relative-links).
-
-You can only use snippet blocks for internal pages. If you add a snippet block to a page in a published space, the public documentation will show the block as a broken link.
-
-{% hint style="warning" %}
-**Note:** If you use a snippet block, but then [convert your snippet into a page](../../snippets/snippets-beta.md#convert-a-snippet-to-a-page) in your documentation, your snippet block will still link back to the original snippet, which will be archived.
-{% endhint %}
-
-### Representation in Markdown
-
-```
-{% raw %}
-{% content-ref url="./" %} . {% endcontent-ref %}
-{% endraw %}
-```
diff --git a/content-editor/blocks/table.md b/content-editor/blocks/table.md
deleted file mode 100644
index 331e5c45..00000000
--- a/content-editor/blocks/table.md
+++ /dev/null
@@ -1,83 +0,0 @@
----
-description: >-
- Keep information organized and make documenting data easier by adding a table
- to your page.
----
-
-# Tables
-
-You can add tables to better organize your information in a GitBook page. As you would expect, you can add and remove columns, set the type of data in a column, choose text alignments, and much more.
-
-{% hint style="info" %}
-You can make table blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
-{% endhint %}
-
-
-
-### Table block options
-
-When you open the Options menu to the left of a table block, you’ll have a number of options to change the apperance and manage the data inside the table:
-
-* **Table/Cards:** Choose to display your data as either a table block or [a cards block](cards.md). GitBook populates both these blocks using the same data, so you can switch between them depending on the look and design you want.
-* **Add column:** Add a new column to the right of your table. You can choose column type using the menu, or just click **Add column** to add a text column.
-* **Insert row:** Add a new row to the bottom of your table.
-* **Show header:** Hide or show the top totle row of your table. Depending on the data you’re display, you may not need a title row in your table, so you can disable it here.
-* **Reset column sizing:** If you’ve changed the column widths, this will reset them all to be equal again.
-* **Visible columns:** Choose which columns are visible and which are hidden. If you have hidden columns in your table, this menu is where you can make them visible again.
-* **Full width:** Make your table span the full width of your window. This is great for tables with lots of columns.
-* **Delete:** Deletes the table block and all of it’s content.
-
-### Changing a column type
-
-Depending on the data you want to display, you can set table columns can have different data types. These add formatting, embellishments or restrictions to every cell in the column:
-
-* **Text:** A standard text column, with standard formatting support.
-* **Number:** A number column, with or without floating digits.
-* **Checkbox:** A checkbox on each line that can be checked or unchecked.
-* **Select:** You can select data from a list of options that you can define by opening the columns’s **Options menu** and choosing **Manage options**. This can be single-choice or multiple-choice.
-* **Users:** You can add the name and avatar of a member of your organization. This can be single-choice or multiple-choice.
-* **Files:** You can reference a file in the space. You can upload new files when populating cells in the column.
-* **Rating:** A star rating. You can configure the maximum rating by opening the column’s **Options menu** and choosing **Max**.
-
-Use the column’s **Option menu** to change a column’s type. When you change a column type, you’ll see a prompt asking you to confirm the change, as column data could be deleted or broken by this action.
-
-### Resizing columns
-
-Hover over a column’s edge and drag to resize it. GitBook stores column sizes as a percentage of the overall width, which allows for relative sizing based on the overall width of the table.
-
-### Scrolling tables
-
-Tables that are wider than the editor container will be horizontally scrollable.
-
-### Column options
-
-To reorder columns, click and drag on the **Options** button in the column you want to move.
-
-Inside the Options menu you can also switch automatic sizing on and off, add a new column to the right, hide the column, or delete the column.
-
-### Row options
-
-To open a row’s Options menu, hover over the row and click the **Options** button that appears on the left of it. You’ll see a number of options
-
-* **Open row:** Open the row in a modal that shows all of its data. Here you can quickly change row types, edit data, and see data in hidden columns.
-* **Insert above/below:** Add a new row above or below the currently-selected row.
-* **Add column:** Add a new column on the right of the table.
-* **Delete row:** Permanently remove all the data in the row from your table.
-
-### Images in tables
-
-When you click into a table cell, you can hit the / key to insert images. Note that this will not work in the header row.
-
-
-
-### Representation in Markdown
-
-```markdown
-# Table
-
-| | | |
-| - | - | - |
-| | | |
-| | | |
-| | | |
-```
diff --git a/content-editor/blocks/tabs.md b/content-editor/blocks/tabs.md
deleted file mode 100644
index 8c792def..00000000
--- a/content-editor/blocks/tabs.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-description: >-
- Add a block with multiple tabs to a page, so you can display large blocks of
- related information without creating a long, hard-to-navigate page.
----
-
-# Tabs
-
-A tab block is a single block with the option to add multiple tabs.
-
-Each tab is like a mini page — it can contain multiple other blocks, of any type. So you can add code blocks, images, integration blocks and more to individual tabs in the same tab block.
-
-They’re great for adding similar or related information without making your page really long — such as code snippets in multiple languages, or instructions for completing the same tasks on different operating systems.
-
-### Add or delete tabs
-
-To add a new tab to a tab block, hover over the edge of a tab and click the `+` button that appears. To delete a tab, open the tab’s **Options menu** then select **Delete**.
-
-### Example
-
-Here is an example that lists instructions relevant to specific platforms:
-
-{% tabs %}
-{% tab title="Windows" %}
-Here are the instructions for Windows
-{% endtab %}
-
-{% tab title="OSX" %}
-Here are the instructions for macOS
-{% endtab %}
-
-{% tab title="Linux" %}
-Here are the instructions for Linux
-{% endtab %}
-{% endtabs %}
-
-### Representation in Markdown
-
-```markdown
-{% raw %}
-{% tabs %}
-
-{% tab title="Windows" %} Here are the instructions for Windows {% endtab %}
-
-{% tab title="OSX" %} Here are the instructions for macOS {% endtab %}
-
-{% tab title="Linux" %} Here are the instructions for Linux {% endtab %}
-
-{% endtabs %}
-{% endraw %}
-```
diff --git a/content-editor/blocks/task-list.md b/content-editor/blocks/task-list.md
deleted file mode 100644
index c468b985..00000000
--- a/content-editor/blocks/task-list.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: "Add a task list to a page, then check off the tasks as you complete them —\_perfect for to-dos."
----
-
-# Task lists
-
-Task lists allow you to create a list of items with checkboxes that you can check or uncheck. This is useful for tracking project items, creating playbooks and more.
-
-{% hint style="info" %}
-**Note:** Readers of your published space will not be able to 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
- * [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`.
-
-### 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, unidented using `shift` + `tab`.
-```
diff --git a/content-editor/blocks/unordered-list.md b/content-editor/blocks/unordered-list.md
deleted file mode 100644
index 14e9c68c..00000000
--- a/content-editor/blocks/unordered-list.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-description: "Add an unordered list block to a page to quickly create bullet point lists —\_with indents if needed."
----
-
-# Unordered 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
-```
diff --git a/content-editor/broken-links.md b/content-editor/broken-links.md
deleted file mode 100644
index 3fb1ae3a..00000000
--- a/content-editor/broken-links.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-icon: link-slash
-description: Find and replace broken relative links across your spaces.
----
-
-# Broken links
-
-{% hint style="info" %}
-This feature is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-
Broken links panel
-
-You can add a few different [types of links](editing-content/inline.md#links) to your pages in GitBook. If someone has broken a [relative link](editing-content/inline.md#relative-links) while making a change request by updating it or changing its location, you’ll see a notification letting you know there’s something to fix.
-
-{% hint style="info" %}
-Broken link detection currently works only for relative links to other GitBook content in your organization. It will not detect broken links to external URLs.
-{% endhint %}
-
-To view broken links, click the broken link symbol in the [space sub-nav](editor/navigation.md#space-header-and-sub-navigation) when inside a change request.
-
-### Product Demo
-
-{% embed url="https://www.youtube.com/watch?v=dC53NpIQ07Q" %}
-
-### How to fix a broken link
-
-If GitBook finds a broken link, you’ll see a notification in this section with a link to the page that includes the broken link. Then, simply replace or update the link with a valid one.
-
-As you view your broken links, you can also set the scope and filter of broken links inside of the sidebar:
-
-
Filter your broken links, or set the scope of the scan.
-
-### Scope
-
-#### Current change request
-
-This will find newly broken links within the scope of the current change request you are working in.
-
-#### Current space
-
-This will find broken links within the scope of the current space you are in.
-
-### Filter by
-
-#### Broken links
-
-Show any broken or missing links in the space or change request you are in.
-
-#### Internal links
-
-This filter is useful for making sure your published docs don’t link to internal content within your GitBook organization. It’ll show any links to internal, unpublished content that readers of your published content won’t have access to (i.e. links that start `app.gitbook.com/o//…`). You can fix them by replacing the links with the URL of the published GitBook page.
-
diff --git a/content-editor/editing-content/README.md b/content-editor/editing-content/README.md
deleted file mode 100644
index 6a54a718..00000000
--- a/content-editor/editing-content/README.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-description: >-
- With GitBook, you can edit your content in a number of ways, including using
- rich text, inline content, and Markdown.
-icon: pen-to-square
----
-
-# Editing content
-
-You can build your documentation with a range of blocks and inline content, formatting it to match your needs.
-
-{% hint style="warning" %}
-Only users with [editor permissions or higher](../../account-management/member-management/roles.md) can edit content in a space.
-{% endhint %}
-
-### Learn more about
-
-
Formatting
Learn more about which formatting options are available.
-
diff --git a/content-editor/editing-content/formatting.md b/content-editor/editing-content/formatting.md
deleted file mode 100644
index 438c3f8e..00000000
--- a/content-editor/editing-content/formatting.md
+++ /dev/null
@@ -1,77 +0,0 @@
----
-description: >-
- You can format your content in a number of ways, using the context menu or
- keyboard shortcuts in the GitBook editor.
----
-
-# Formatting your content
-
-To format your text, simply select it and choose one of the formats from the context menu — or use a keyboard shortcut or Markdown syntax. We’ve listed those out below:
-
-
bold, italics context menu with text highlighted
-
-{% 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 page](../../help-and-faq/keyboard-shortcuts.md) 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 space, we recommend [using a relative link](inline.md#relative-links).
-
-This is [a link to an external page](https://www.gitbook.com).
-
-This is a [link to another page in this space](../blocks/).
-
-This is a [link to a section on this page](formatting.md#code).
-
-This is [a link that starts an email to a specific address](mailto:support@gitbook.com).
diff --git a/content-editor/editing-content/inline.md b/content-editor/editing-content/inline.md
deleted file mode 100644
index 44bfed2a..00000000
--- a/content-editor/editing-content/inline.md
+++ /dev/null
@@ -1,99 +0,0 @@
----
-description: >-
- Want to add more than just text to a page? You can use the inline palette to
- add images, links, math & TeX, and more.
----
-
-# Inline content
-
-The inline palette let’s 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.
-
-{% hint style="info" %}
-The forward slash will be replaced by the content you choose to insert.
-{% endhint %}
-
-
The inline palette lets you quickly add content to any block.
-
-### 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.
-
-### 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](../blocks/insert-images.md), which is as wide as your content.
-
-{% hint style="info" %}
-[Image blocks](../blocks/insert-images.md) offer more options, including more sizes and the ability to add a caption — but will not appear inline with your text.
-{% endhint %}
-
-### 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.
-
-### Links
-
-You can insert three different types of links:
-
-* [Relative links](inline.md#relative-links)
-* [Absolute links](inline.md#absolute-links)
-* [Email address `mailto` links](inline.md#email-address-mailto-links)
-
-#### Relative links
-
-Relative links are links created by linking to [pages](../editor/content-structure/content-in-a-space.md) or [snippets](../../snippets/snippets-beta.md) that already exist in your space. 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 get fewer broken links.
-
-{% hint style="info" %}
-**Note:** If you link to a snippet, but then [convert your snippet into a page](../../snippets/snippets-beta.md#convert-a-snippet-to-a-page) in your documentation, your link will still send people to the original snippet, which will be archived.
-{% endhint %}
-
-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`.
-
-#### 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`.
-
-### Math & TeX
-
-Using this option, you can create an inline math formula in your content, like this: $$f(x) = x * e^{2 pi i \xi x}$$. 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](../blocks/math-and-tex.md) by opening the command palette in an empty block and choosing the second Math & TeX option.
-{% endhint %}
diff --git a/content-editor/editing-content/live-edits.md b/content-editor/editing-content/live-edits.md
deleted file mode 100644
index 8423d96a..00000000
--- a/content-editor/editing-content/live-edits.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-description: Collaborate on pages in real-time with your teammates
----
-
-# Live edits
-
-**Live editing** is the default editing mode for any newly-created GitBook space. A space in live edit mode is editable by anyone with the [right permissions](../../account-management/member-management/roles.md).
-
-With live editing enabled, you can see the avatars of anyone currently viewing the space in the top-right corner.
-
-GitBook supports live collaboration, meaning you’ll be able to work on the same document with multiple members at the same time.
-
-## Toggling live edit mode
-
-You can toggle live edit mode in a space by selecting **Lock live edits** or **Unlock live edits** from the space’s **Action menu** .
-
-
You can lock or unlock live edits on a space from the Actions menu.
-
-### When is live editing _not_ available?
-
-You cannot unlock live editing if:
-
-1. a space is [published](../../published-documentation/overview.md) with the **In collection**, **Public**, or **Unlisted** [visibility option](../../collaboration/share/share-a-space.md). We know this is a limitation, and we hope to change this in the future.
-2. a space has [GitHub or GitLab Sync](../../integrations/git-sync/) enabled.
-
-{% hint style="info" %}
-Only users with the **admin** or **creator** [roles](../../account-management/member-management/roles.md) can lock or unlock live edits.
-{% endhint %}
diff --git a/content-editor/editing-content/markdown.md b/content-editor/editing-content/markdown.md
deleted file mode 100644
index cccc003e..00000000
--- a/content-editor/editing-content/markdown.md
+++ /dev/null
@@ -1,67 +0,0 @@
----
-description: >-
- GitBook supports Markdown directly in the editor, so you can quickly and
- easily create content using common syntax.
----
-
-# Markdown
-
-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**` | **text** |
-| Italic | `_italic_` | _italic_ |
-| Strikethrough | `~strikethrough~` | ~~strikethrough~~ |
-
-### 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.
-
-{% 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 %}
-
-### 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.
-
-{% hint style="info" %}
-When writing any kind of list, hit `Tab` to add a indent, and `Shift+Tab` to outdent.
-{% endhint %}
-
-### 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.
diff --git a/content-editor/editing-content/write-and-edit-with-ai.md b/content-editor/editing-content/write-and-edit-with-ai.md
deleted file mode 100644
index 43931392..00000000
--- a/content-editor/editing-content/write-and-edit-with-ai.md
+++ /dev/null
@@ -1,67 +0,0 @@
----
-description: Use GitBook AI to generate and build content for your page
----
-
-# Write with GitBook AI
-
-You can use GitBook AI to create content on any empty line on your page. It can create all kinds of content — formatted in Markdown — including code samples, templates, page summaries and more.
-
-{% hint style="warning" %}
-GitBook AI is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-### Product Demo
-
-{% embed url="https://www.youtube.com/watch?v=7sgcjb8RtjE" %}
-
-### How to write with GitBook AI
-
-Press `Space` on any empty line, or type `/` and choose **Write with AI** to enter GitBook AI’s writing mode.
-
-
-
-You can instantly start typing any prompt you want. GitBook AI will analyze the prompt and generate content based on it. For example:
-
-> Write me a two-paragraph overview of why documentation is important for product teams.
-
-Alternatively, you can also choose from one of the suggested prompts or prompt starters:
-
-#### Continue writing
-
-If you click this option, GitBook AI will analyze the content on your current page and then generate more content based on that.
-
-#### Explain…
-
-Click this and then tell GitBook AI what you want it to explain. This isn’t limited by content on your page, so you can ask it to explain anything at all.
-
-#### Summarize
-
-As you can imagine, this option will summarize all the content on your page — great for writing a TL;DR at the bottom of a detailed document, or adding a quick summary at the top for people just checking in.
-
-#### Explain this
-
-This will break down the complex information on your page and explain it in simpler language — including explaining acronyms and other jargon. This is perfect if the page you’re reading involves a lot of complex information, or you want to add an explainer for less technical folks.
-
-#### Translate
-
-This mode will translate your current page into one of a set number of languages. If you want to translate into a language that’s not on the list, simply type it into the prompt box.
-
-### FAQs
-
-
-
-How does GitBook AI use my data?
-
-We always follow [our data protection practices](https://policies.gitbook.com/privacy-and-security/statement) to keep your data private.
-
-GitBook AI does not use your data to train AI models. We will only share the information you add to GitBook AI with OpenAI for the sole purpose of providing you with GitBook AI’s features. Take a look at [OpenAI’s privacy policy](https://openai.com/enterprise-privacy) for more information.
-
-
-
-
-
-How much does GitBook AI cost?
-
-GitBook AI is available as part of GitBook’s Pro and Enterprise plans. If you have a Free or Plus plan, you’ll need to upgrade to use GitBook AI writing and editing. [Visit our pricing page](https://www.gitbook.com/pricing) to find out more about upgrading to Pro.
-
-
diff --git a/content-editor/editor/README.md b/content-editor/editor/README.md
deleted file mode 100644
index a1544f7c..00000000
--- a/content-editor/editor/README.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-icon: display
-description: >-
- GitBook’s editor supports different writing formats, interactive blocks,
- helpful ways to organize your content and more.
----
-
-# Editor
-
-GitBook offers a range of block types for you to add to your content inline — from simple text and tables, to code blocks and more. These elements will make your pages more useful to readers, and offer extra information and context.
-
-And when it comes to organizing your content, you have multiple options depending on your needs. Find out more below.
-
-{% hint style="info" %}
-**Permissions**\
-Only users with [editor permissions or higher](../../account-management/member-management/roles.md) can edit pages.
-{% endhint %}
-
-### Learn more about
-
-
Navigation
Learn about the UI and how to navigate pages in GitBook.
-
diff --git a/content-editor/editor/content-structure/README.md b/content-editor/editor/content-structure/README.md
deleted file mode 100644
index a9748e83..00000000
--- a/content-editor/editor/content-structure/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-description: Learn how to use pages, page groups, spaces and collections
----
-
-# Content structure
-
-The structure of your content in GitBook is organized through pages, spaces and collections. Pages live inside of spaces, and collections are groups of spaces.
-
-{% hint style="info" %}
-**Permissions**
-
-Anyone with [editor permissions](../../../account-management/member-management/roles.md) and higher can create pages. People with [creator permissions](../../../account-management/member-management/roles.md) and higher can create new spaces and collections.
-{% endhint %}
-
-### Product Demo
-
-{% embed url="https://youtube.com/watch?v=K8HMCxCJWI8" %}
-
-### Learn more about:
-
-
diff --git a/content-editor/editor/content-structure/content-in-a-space.md b/content-editor/editor/content-structure/content-in-a-space.md
deleted file mode 100644
index af8521ba..00000000
--- a/content-editor/editor/content-structure/content-in-a-space.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-description: Add pages, groups, external links, and more to your GitBook spaces
----
-
-# Pages
-
-A page in GitBook is the place where you add, edit and embed content. Pages always live inside a [space](what-is-a-space.md), allowing you to group up related content and create different sections for the topics or areas you’re covering.
-
-### Table of contents
-
-You can create as many pages as you need in a space. They’re all visible on the left side of your screen in your space’s [table of contents](../navigation.md#table-of-contents).
-
-### Hide a page from the table of contents
-
-You can hide a page or group of pages from your site's table of contents by clicking the page’s **Action menu** and toggling **Hide page**.
-
-Hidden pages will still be indexable by search and GitBook AI, but will not appear in the table of contents in your published site. Hidden pages will still be accessible through direct links.
-
-If hidden the following will appear in the front matter of the markdown file when using Git Sync:
-
-
---
-hidden: true
----
-
-
-{% embed url="https://www.youtube.com/watch?v=caN1kQYXb8I" %}
-
-### Organizing your content
-
-There are three types of pages you can add:
-
-#### Pages
-
-A page has a title, and optional description, and an area where you can write and add any kind of content.
-
-You can nest pages by dragging and dropping a page below an other in the table of contents. Doing this creates a subpage.
-
-{% hint style="info" %}
-**Tip:** There’s no limit to page nesting, but we’d recommend you avoid more than three levels of nesting to avoid an overly-complex navigation.
-{% endhint %}
-
-When you change the title of a page, the page’s slug (the part at the very end of the URL, e.g. `/hello-world`) will also change — unless you’ve manually set the page’s slug previously.
-
-You can change the title and the slug of a page at any time by clicking opening the page’s **Action menu** and choosing **Rename**.
-
-#### Page groups
-
-Page groups make it easy to bring pages together into sections that cover related content.
-
-Page groups can only live at the **top level** of the [table of contents](../navigation.md#table-of-contents). You cannot nest page groups inside page groups.
-
-To change the title and slug of a page group, click the **Action menu** icon next to the group title in the table of contents and choose **Rename**.
-
-#### External links
-
-External links are simply links to external sites and resources. Adding a link doesn’t create a page in your content. Clicking one in the sidebar will immediately open the link in a new tab.
-
-### Create a new page
-
-
You can create a new page or page group from table of contents.
-
-When in [live edit](../../editing-content/live-edits.md) mode or in a [change request](../../../collaboration/change-requests.md), you can create a new page by clicking **Add new page** > **New document page** at the bottom of your table of contents.
-
-Alternatively, you can hover between pages in the table of contents and click the **+** icon that appears.
-
-Once you’ve created a new page, you can add content to it using the [editor](../).
-
-### Create a page group
-
-Just like creating a new page, you can create a page group by choosing **Add new page** > **New group** from the bottom of your table of contents.
-
-### Create an external link
-
-To add an external link to your space, click the **Add new page** button at the bottom of the table of contents, then choose **New link**. Give the link a title — this will appear in the table of contents — and then add the URL and click **Insert**.
-
-### Add an icon or emoji to your page
-
-{% embed url="https://www.youtube.com/watch?v=p6gYpjDQOn4" %}
-
-To add better visibility for readers when skimming your table of contents, you can add an optional icon or emoji to an individual page. The icon or emoji will appear 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.
-
-
-
-#### Customize the icon style
-
-You can choose the style and weight of the icon in your published site's settings. You can find the icon's style settings and more [here](../../../published-documentation/customization/space-customization.md#styling).
-
-### Can’t see the option to create a new page?
-
-{% hint style="warning" %}
-If [live edits](../../editing-content/live-edits.md) are disabled for your space, you’ll need to create or edit a [change request](../../../collaboration/change-requests.md). Once you’re in a change request, the **New page** button (which allows you to create pages, page groups and links) will be available in the table of contents.
-
-Alternatively, you may not have the correct [permissions](../../../account-management/member-management/permissions-and-inheritance.md) to edit a page.
-{% endhint %}
diff --git a/content-editor/editor/content-structure/what-is-a-collection.md b/content-editor/editor/content-structure/what-is-a-collection.md
deleted file mode 100644
index 35d539ef..00000000
--- a/content-editor/editor/content-structure/what-is-a-collection.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-description: Organize your spaces and group related ones together using collections
----
-
-# Collections
-
-Collections are groups of spaces focused around a specific topic, team or purpose. You can think of them as a folder for your spaces.
-
-Collections allow you to:
-
-* organize your content by similar topics or ideas
-* manage space [permissions](../../../account-management/member-management/permissions-and-inheritance.md) at scale by allowing you to override the organization-level defaults
-
-
The main view of a collection, with other collections and spaces inside.
-
-### Create a collection
-
-Click the **+** button next to the **Documentation** header in the sidebar to create a new collection. You can also create a collection or space within another collection from the collection’s main page.
-
-
You can create a collection from the sidebar, or from within another collection.
-
-### Move a collection
-
-You can move a collection by opening the **Action menu** , selecting **Move collection to…** and choosing a destination. Alternatively, you can drag and drop collections in the sidebar to move or reorder them.\
-\
-You can move collections into other collections — or even to other organizations, if you have an [admin role](../../../account-management/member-management/roles.md) in both.
-
-### Nested collections
-
-You can nest collections inside each other, creating a collection -> sub-collection -> space hierarchy.
-
-Open a collection and you can click **New collection** from the collection’s main page to create a sub-collection.
-
-To move one collection into another, click **Move collection to…** from the collection’s **Action menu** and then choose its new location. Alternatively, you can drag and drop the collection to its new location.
-
-### How to delete a collection
-
-You can delete a collection by opening it’s **Action menu** and selecting **Delete**.
-
-{% hint style="danger" %}
-**Deleting a collection is final**, but spaces inside a deleted collection will move to the **Trash** and can be restored up to seven days after deletion. You can access the Trash from the bottom of the sidebar.
-{% endhint %}
diff --git a/content-editor/editor/content-structure/what-is-a-space.md b/content-editor/editor/content-structure/what-is-a-space.md
deleted file mode 100644
index c69076cd..00000000
--- a/content-editor/editor/content-structure/what-is-a-space.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-description: >-
- Organize the content you create and publish into spaces, which help you group
- related pages together
----
-
-# Spaces
-
-A space is a project that lets you work on a collection of related pages. Imagine it as a virtual book where you can start writing pages individually or collaborate asynchronously with your team members.
-
-
A GitBook space — a collection of pages on a related topic.
-
-### Create a space
-
-Click the **+** button next to the **Spaces** header in the sidebar and choose **New space** to create a new space. You can also create a new space from a [collection](what-is-a-collection.md).
-
-
You can create a new space from the sidebar by hitting the + next to the Documentation header.
-
-### Duplicate a space
-
-To duplicate a space, open that space's **Action menu** in the sidebar and select **Duplicate**.
-
-Duplicating a space will create a copy of the source space, in the same location (organization, collection, sub-collection, etc.).
-
-### Move a space
-
-You can move a space by opening the space’s **Action menu** in the sidebar, selecting **Move space to…** and choosing a destination. Alternatively, you can drag and drop spaces in the sidebar to move or reorder them.\
-\
-You can move spaces between collections or even organizations, as long as you have an [admin role](../../../account-management/member-management/roles.md) in both.
-
-### Delete a space
-
-You can delete a space by opening the space’s **Action menu** in the sidebar and selecting **Delete**.
-
-{% hint style="warning" %}
-**Deleted spaces can be restored from the Trash for up to 7 days**. After this, they will be permanently deleted.
-{% endhint %}
diff --git a/content-editor/editor/navigation.md b/content-editor/editor/navigation.md
deleted file mode 100644
index 2e5783c8..00000000
--- a/content-editor/editor/navigation.md
+++ /dev/null
@@ -1,146 +0,0 @@
----
-description: Learn about the UI and how to navigate pages in GitBook.
----
-
-# Navigation
-
-GitBook is split into different sections to make it easier to organize and manage the content you create. Read on to learn more about these sections, and how they help you build an organized and easily searchable content structure.
-
-### The sidebar
-
-
The GitBook sidebar holds all of your documentation, as well as notifications, the search bar, snippets and more.
-
-The sidebar allows you to see and overview of your GitBook organization at a glance. The sidebar contains:
-
-* **Organization switcher**\
- If you’re a part of multiple organizations, you can see and switch between them here. You can also create a new organization from this menu.
-* **Notifications**\
- When you’re tagged in a comment or conversation, or when there is important activity in a space you’re working in, you’ll get a [notification](../../collaboration/notifications.md) to show you what’s new.
-* **Ask or search**\
- Powered by [GitBook AI](../searching-your-content/gitbook-ai.md), you can ask questions in natural language, or search through the different spaces and content in your organization.
-* **Home**\
- The Home page allows you to see everything your team is working on at a glance. View open change requests, discussions and comments, recent page edits and more.
-* **Docs sites home**\
- Click this to visit the overview page for all the docs sites you have created in your organization.
-* **Snippets**\
- With [snippets](../../snippets/snippets-beta.md), you can capture complex information from third-party tools. GitBook AI extracts that valuable knowledge within, and documents it for you in seconds.
-* **Integrations**\
- GitBook [integrations](broken-reference/) supercharge your content, allowing you to embed more into your pages, or add information to your knowledge base from other apps. Head to the [integration listing page ](../../integrations/third-party-integrations.md)to see all the available integrations.
-* **Docs sites**\
- Toggle this section to view all the [docs sites](../../published-documentation/publish-a-docs-site/) in your organization right in the sidebar and jump to one with a click.
-* **Spaces**\
- The spaces section is where you’ll find the [collections](content-structure/what-is-a-collection.md) and [spaces](content-structure/what-is-a-space.md) you create when adding more content. Head to our [content structure](content-structure/) section to find out more.
-* **Settings**\
- You’ll find [personal settings](../../account-management/account-settings.md) and [organization settings](../../account-management/organization-management.md) at the bottom of the sidebar. Here, you can also toggle light/dark mode, or get help from our support team if needed.
-* **Trash**\
- Deleted spaces appear in the trash. You can restore them for up to seven days — after that, they’re permanently deleted.
-
-### Table of contents
-
-
The table of contents lists all the pages and links in your selected space.
-
-The table of contents is a list of [pages, links, and groups](content-structure/content-in-a-space.md#organizing-your-content) that make up a space. You’ll find it to the right of the sidebar. It’s specific to the space you’re currently viewing.
-
-From the table of contents you can:
-
-* create new [pages](navigation.md#pages) and subpages
-* create [page groups](navigation.md#groups)
-* add [external links](navigation.md#external-links)
-* [import external docs](../import.md) like websites or Markdown files
-* access [the Actions menu](navigation.md#the-actions-menu) for individual pages.
-
-If you want to give more focus to the content of your page, you can temporarily hide the table of contents by hovering your cursor next to it and clicking the **Hide** button that appears. To make it appear again, hover your cursor near the edge of the page and click the **Show** button .
-
-### Space overview & space header
-
-
The space header sits at the top of the editor, and offers options that apply to the whole space.
-
-The space overview contains information about the space you’re currently viewing. It lets you do things like [publish and share](../../published-documentation/overview.md) your space, configure [GitHub or GitLab sync](../../integrations/git-sync/), and more.
-
-{% hint style="info" %}
-The space overview & space header may look different depending on the mode you’re currently in. See [change requests](../../collaboration/change-requests.md) for more info.
-{% endhint %}
-
-#### Space overview
-
-The space overview appears at the top of GitBook when viewing a space. It includes:
-
-* **The space’s breadcrumbs**\
- A full, linear list of the collections or docs sites the space lives in.
-* **Collaborators**\
- The avatar of anyone else who’s currently viewing a page in your space, with colored circles to show their cursor color. Click an avatar to jump to the page they’re currently viewing.
-* **Git Sync configuration**\
- The [GitHub and GitLab Sync](../../integrations/git-sync/) configuration for your space.
-* **The Share menu**\
- Allows you to publish and share your space. You can also invite others to [collaborate](broken-reference/) through this menu.
-* **Actions menu** \
- Offers a list of actions for your space. Similar to [page actions](navigation.md#the-actions-menu), the available actions for a space will differ depending on the mode you’re currently in.
-
-#### Space header
-
-The space header is located directly beneath the space overview, and lets you collaborate with others on your space, customize it’s look, and more. It includes:
-
-* **The space emoji or icon**\
- You can choose an emoji or icon for your space, to help you easily identify it in the sidebar.
-* **The space name**\
- The name of the space that will appear in the sidebar, and your documentation if and when you choose to publish it.
-* **Comments**\
- See the [comments and discussions](../../collaboration/comments-discussion.md) you and your team have had about the space content.
-* **Broken links**\
- Any [broken links](../broken-links.md) that have been found in the current space or change request.
-* **Change requests**\
- Create, update, and delete [change requests](../../collaboration/change-requests.md) in your space.
-* **The edit button**\
- If your space is published, or someone has locked[ live edits](../editing-content/live-edits.md), the **Edit in change request** button will appear in the space header. It lets you start a new [change request](../../collaboration/change-requests.md) to edit content.
-
-### Content editor
-
-The editor is the main part of your space, where you can write or insert content in GitBook.
-
-In addition to the multiple [content blocks](../blocks/) you can insert, you can also [embed content](../blocks/embed-a-url.md) from other places, such as [integrations](../../integrations/third-party-integrations.md).
-
-### Page title and description
-
-At the top of each page you can set a **title**, add an optional **emoji**, and write a **description**. The title you use will appear in the table of contents, and forms your page’s URL slug when published.
-
-Your page description can be a maximum of 200 characters long, and will act as the preview text for your page in search engines.
-
-{% hint style="info" %}
-You can change the URL slug for a page by choosing **Page Actions** > **Rename**. Find out more about [Page Actions](navigation.md#page-options) below.
-{% endhint %}
-
-### The Actions menu
-
-The page’s Actions menu allows you to do things like duplicate, rename or delete your page.
-
-You can open the Actions menu using the icon that appears when hovering over your page in the sidebar, or from the icon next to the page title.
-
-{% hint style="info" %}
-The type of actions available will depend on whether you’re in live editing mode, a change request, or in a space with [locked edits](../editing-content/live-edits.md).
-{% endhint %}
-
-### Page options
-
-
The Page options side panel offers customization options for your documentation and navigation.
-
-With [page options](../../published-documentation/customization/page-layouts.md), you to customize your documentation layout and navigation. You can only access page options if you’re in an editing mode.
-
-You can open the **Page options** side panel by opening the page’s **Action menu** and choosing **Options**, or by hovering over the main title of the page and clicking **Page options** when it appears.
-
-{% hint style="info" %}
-Certain changes, such as disabling the table of content, only apply to published documentation and may not be visible in the editor.
-{% endhint %}
-
-### Page outline
-
-
The page outline shows H1 and H2 headings, allowing you to quickly jump to a specific section on an individual page.
-
-The **page outline** sits on the right-hand side of the editor, and makes it easy to jump directly to the section of the page you’re looking for.
-
-Any [Heading 1 or Heading 2 blocks](../blocks/heading.md) you add to the page will appear in the page outline listed here.
-
-The page outline will appear in your published site, too. You can toggle it on or off in the [**Page options**](navigation.md#page-options) side panel.
-
-{% hint style="info" %}
-If you can’t see the right-hand column of the app, it may be because your browser window is less than 1430 pixels wide. Your browser window needs to be at least 1430 pixels wide to see and use the page outline.
-{% endhint %}
diff --git a/content-editor/import.md b/content-editor/import.md
deleted file mode 100644
index 4a2cfee1..00000000
--- a/content-editor/import.md
+++ /dev/null
@@ -1,76 +0,0 @@
----
-icon: arrow-up-to-line
-description: "Find out how to easily migrate your existing documentation —\_and which formats GitBook supports."
----
-
-# Import
-
-There are two methods for importing content into GitBook:
-
-1. [Using our import tool](import.md#using-our-import-tool)
-2. [Using Git Sync](import.md#importing-via-git-sync)
-
-### Using our import tool
-
-You can migrate and unify existing documentation in GitBook using the import tool. You have the option to import single or multiple pages — although some limits apply, which we’ll explain below.
-
-{% hint style="info" %}
-**Permissions**\
-Only users with [editor permissions or higher](../account-management/member-management/roles.md) can edit pages.
-{% endhint %}
-
-#### Supported import formats
-
-GitBook supports imports from websites or files in the following formats:
-
-* Markdown (.md or .markdown)
-* HTML (.html)
-* Microsoft Word (.docx)
-
-We 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.
-
-#### The Import panel
-
-When you create a new [space](editor/content-structure/what-is-a-space.md), you’ll have the option to import content from the bottom sheet of the first empty page:
-
-Alternatively, you can always import a page or subpage by selecting **New page** > **Import new pages** in the [table of contents](editor/navigation.md#table-of-contents), or opening the Actions menu for a page and choosing **Import subpages**.
-
-
-
-
There are two ways to import content into GitBook.
-
-
-
-After choosing an input source, you can select the file you’d like to import.
-
-{% hint style="warning" %}
-Although GitBook supports importing content from different sources, the result may differ from your source due to differences in product features and document formats.
-{% 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**.
-
-### Importing via Git Sync
-
-If you want to import large amounts of content, you can use our [Git Sync](../integrations/git-sync/) feature, which has no limitation on the amount of content that can be imported.
-
-To import using Git Sync, you’ll first need to add your content to a GitHub or GitLab repository — or folder if you're using a monorepo setup — as Markdown files. If your current tool does not support Markdown export, various online tools can assist with conversion from other formats, such as PDF, HTML, etc.
-
-Once you’ve set up your Git repository, simply [set up a Git Sync integration](../integrations/git-sync/) in your GitBook organization. Be sure to select the direction **GitHub -> GitBook** when choosing the initial sync direction.
-
-{% hint style="info" %}
-If you’re having trouble with the import process using either method above, please [get in touch with our support team](mailto:support@gitbook.com) — they’d be happy to help.
-{% endhint %}
diff --git a/content-editor/overview.md b/content-editor/overview.md
deleted file mode 100644
index 8df4a43c..00000000
--- a/content-editor/overview.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-icon: bullseye-arrow
-description: Edit pages, collections, content and more.
----
-
-# Overview
-
-
-
-
The GitBook editor.
-
-
-
-GitBook has a powerful block-based editor that allows you to seamlessly create, update, and enhance your content.
-
-### Learn more about
-
-
Editor
Learn more about GitBook’s navigation, content structure, and more.
diff --git a/content-editor/searching-your-content/README.md b/content-editor/searching-your-content/README.md
deleted file mode 100644
index 7964e23a..00000000
--- a/content-editor/searching-your-content/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-description: >-
- Find what you’re looking for faster with keyword search and AI-powered smart
- search.
-icon: magnifying-glass
----
-
-# Searching content
-
-Whether you’re working within the GitBook app or your visitors are reading your published content, GitBook’s search functions help to make it easy to find what you’re looking for.
-
-You can use quick find to look for specific words or phrases, or you can ask GitBook AI a question. It’ll scan through your docs and summarize an answer in seconds, with references to help you find out more.
-
-{% hint style="info" %}
-**Permissions**\
-For **published content**, anyone can use the built-in **Search** bar in the top-right of the screen to find the answers or pages they’re looking for.
-
-For **internal content,** all member roles can use the **quick find** search bar in the top-left of the screen. However, members will only be able to search the internal content they have permission to access.
-{% endhint %}
-
-### Learn more about
-
-
GitBook AI search ✨
A semantic search tool, powered by AI. Ask a question and it will give an answer based on your content.
diff --git a/content-editor/searching-your-content/gitbook-ai.md b/content-editor/searching-your-content/gitbook-ai.md
deleted file mode 100644
index 58171d81..00000000
--- a/content-editor/searching-your-content/gitbook-ai.md
+++ /dev/null
@@ -1,69 +0,0 @@
----
-description: GitBook uses AI to help you find the knowledge you need, faster.
----
-
-# GitBook AI
-
-{% embed url="https://www.youtube.com/watch?v=7sgcjb8RtjE" %}
-
-Simply tell GitBook AI what you want, or ask it a question. It’ll use AI to scan your documentation and give you a simple, semantic answer — with clickable references if you want to dive deeper.
-
-### Which GitBook plans include GitBook AI?
-
-GitBook AI is available to users on the **Pro or Enterprise plans**. If you have a Free or Plus account, you’ll need to upgrade to use GitBook AI search. [Visit our pricing page](https://www.gitbook.com/pricing) to learn more.
-
-### How do I enable GitBook AI?
-
-#### For published content
-
-You can enable GitBook AI for any published space or collection in that space’s or collection’s [customization settings](../../published-documentation/customization/space-customization.md).
-
-Click the **Customize** button, then open to the **Configure** tab and toggle the **Enable** **GitBook AI semantic search** setting on.
-
-#### For internal content
-
-You can also enable GitBook AI for your organization’s internal content, allowing you to ask questions and get semantic answers about your internal knowledge base.
-
-Head to the **Organization settings** page and, in the **General** tab, toggle the **Enable GitBook AI semantic search** setting on.
-
-### How do I use GitBook AI?
-
-Once GitBook AI is enabled, simply type a question into the search bar. GitBook AI will take a few seconds to scan your documentation and summarize the results.
-
-#### Using GitBook AI in published documentation
-
-Let’s give it a try right here in our own public documentation! Firstly, open the search palette by clicking **Ask or search…** in the top-right corner of the page, or by press **⌘ + K** on a Mac or **Ctrl + K** on a PC.
-
-Then simply type your question and press `Enter`. You’ll see a number of suggested questions that you might like to ask.
-
-For this example, in our own docs, you can try: “What makes change requests a powerful GitBook feature?” After a few seconds, you’ll get an answer from GitBook AI.
-
-As well as a summarized answer, below you’ll also see an expandable section that shows the sources that GitBook AI used to create its answer, plus related questions you can click as a follow-up.
-
-{% hint style="warning" %}
-**Note:** GitBook AI does not work across individual published spaces in different collections. **Multi-space search is **_**only**_** available when viewing published** [**GitBook spaces**](../editor/content-structure/what-is-a-space.md) **that live inside of a** [**published collection**](../../collaboration/share/share-a-collection.md)**.**
-{% endhint %}
-
-#### Using GitBook AI in internal documentation
-
-If GitBook AI is enabled for internal content, you’ll be able to do the same thing when logged into the GitBook app: open the quick find command palette, type a question and receive a semantic answer.
-
-
Ask a question with GitBook AI.
-
-#### Integrating GitBook AI with your product
-
-With our API, you can embed GitBook AI into your product or website! This opens up lots of possibilities, including in-app helpers and website chat bots that can respond to questions based on the content in your documentation.
-
-Head to [our developer documentation](https://developer.gitbook.com/gitbook-api/reference/search#get-ai-search-results-from-all-spaces-for-the-currently-authenticated-user) to find out more.
-
-#### How long does it take for GitBook AI to index changes?
-
-When someone makes a change to your content — such as a merged [change request](../../collaboration/change-requests.md) or a new [knowledge snippet](../../snippets/snippets-beta.md) from Slack) it can take **up to one hour** for GitBook to index the changes to and reflect them in AI search results.
-
-#### How does GitBook AI handle my data?
-
-We pass your content to OpenAI to index and process data. OpenAI **does not** use this content for service improvements (including model training). You can find out more about how OpenAI handles data [here](https://openai.com/blog/introducing-chatgpt-and-whisper-apis#developer-focus).
-
-#### How do I prevent hallucinations with GitBook AI search?
-
-If you’re seeing GitBook produce answers that are incorrect, the best method for correcting this is write explicit content around the topic so the AI does not have to guess.
diff --git a/content-editor/searching-your-content/quick-find.md b/content-editor/searching-your-content/quick-find.md
deleted file mode 100644
index e63c3778..00000000
--- a/content-editor/searching-your-content/quick-find.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-description: Search and navigate your documentation fast with quick find.
----
-
-# Search & Quick find
-
-GitBook’s quick find palette lets you search for content across all your organizations, and jump between them fast.
-
-{% hint style="info" %}
-**Permissions**
-
-All [member roles](../../account-management/member-management/roles.md) can use the **quick find**, but members will only be able to search the internal content they have permission to access.
-{% endhint %}
-
-### How to use quick find
-
-****You can open the quick find palette by pressing **⌘ + K** on Mac or **Ctrl + K** on PC.
-
-
The quick find palette
-
-### Search results
-
-Results from the space you’re currently in appear at the top, followed by results from other spaces from the organization you’re currently working in — **as well as other organizations** you are a member of.
-
-When you select a search result from an organization, you’ll switch to browsing that organization. To go back, use quick find to select a document in the organization you were in before, or use [the organization switcher](../editor/navigation.md#the-sidebar) in the sidebar.
-
-{% hint style="info" %}
-We do not currently support the ability to prioritize certain content in quick find results.
-{% endhint %}
-
-### Team permissions
-
-**Quick find** is compliant with your team’s permission settings, meaning that users will only be able to search the content they have permission to access.
-
-{% hint style="warning" %}
-**Note:** Multiple space search is _only_ available when viewing a published [GitBook space](../editor/content-structure/what-is-a-space.md) that lives inside of a [published collection](../../collaboration/share/share-a-collection.md). It is not available across individual published spaces in different collections.
-{% endhint %}
-
-
Search all content in a space
-
-### Content Indexing
-
-We index your content by grouping it into sections. Sections are denoted using [H1, H2 or H3 Headings](../blocks/heading.md), with the content that follows them forming part a section.
-
-Each result shows the first three lines of information below the section header. If your section is too big, your keyword match may not appear in the preview — but don’t worry, quick find still found a match!
diff --git a/creating-content/blocks/README.md b/creating-content/blocks/README.md
new file mode 100644
index 00000000..26e4065c
--- /dev/null
+++ b/creating-content/blocks/README.md
@@ -0,0 +1,52 @@
+---
+description: Add and edit blocks within your content.
+icon: square-dashed-circle-plus
+---
+
+# Blocks
+
+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](hint.md), 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**.
+
+### Full-width blocks
+
+By making your blocks full width, you can create a clear visual hierarchy in your content, or simply give more space to content that needs it.
+
+To make a block full width, click on the **Options menu** next to your block and select **Full width**. This feature is available for the following block types:
+
+* Code Blocks
+* Image blocks
+* Tables
+* Cards
+* API Blocks
+* Integration blocks
+* Columns
diff --git a/creating-content/blocks/cards.md b/creating-content/blocks/cards.md
new file mode 100644
index 00000000..e7d095c7
--- /dev/null
+++ b/creating-content/blocks/cards.md
@@ -0,0 +1,88 @@
+---
+description: "Display information more dynamically with a set of cards —\_with or without images"
+---
+
+# Cards
+
+You can use cards to create a visually pleasing page layout, combining text and images in a grid. They’re ideal for building landing pages or displaying any other content in a non-linear way.
+
+You can adjust [switch between medium or large cards](cards.md#card-size) and link them to the relevant resources.
+
+### Example of a card
+
+
GitBook homepage
Visit our website and find out more about GitBook.
+
+### Adding links
+
+Hover over a card and open its **Options menu** . Here you can add a target link, so users can jump directly to a location when they click the card.
+
+{% hint style="success" %}
+When creating cards, we recommend you use **target links instead of hyperlinks**. With a target link, your readers can click anywhere on the card to access the linked URL.
+{% endhint %}
+
+### Adding images
+
+Hover over a card and open its **Options menu** . Here you can add a cover image to your card. Alternatively, just click the **Add cover image** option on the card itself.
+
+This will open the **Select file** modal. Here you can drag and drop a new image into this, or use an image file you’ve previously uploaded to your space.
+
+#### Adding images for dark mode
+
+You can also add cover images that will only show in dark mode.
+
+To do this, open the card’s **Options menu** and choose **Cover** > **Edit cover** > **Add cover for dark mode**. This will open the **Select file** modal, where you can drag and drop a new image or select a previously-uploaded image.
+
+#### Choosing the right image size
+
+GitBook will automatically crop landscape images to a 16:9 ratio on desktop and mobile. If the images you upload are portrait or have a 1:1 ratio, they will be cropped to 16:9 on desktop and display as square or portrait on mobile.
+
+
On desktop, all card images will display in a landscape 16:9 ratio, regardless of their dimensions. We recommend using the same dimensions for consistency.
+
+
On mobile, square or portrait images will displayed as shown on the left. Landscape images will be displayed as shown on the right.
+
+To keep things consistent across desktop and mobile, we recommend uploading all the images for your cards in a 16:9 format (e.g. 1920px x 1080px).
+
+If you want your cards to adapt their layout depending on the screen size, we’d recommend uploading images with a 1:1 ratio, and the content of your image centered.
+
+### Changing the size of cards
+
+You can select the card size by opening the **Options menu** to the left of your card block. The **Medium** option creates three cards in one horizontal line, while the **Large** option shows two larger cards on each line.
+
+{% hint style="info" %}
+You can make card blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
+{% endhint %}
+
+### Representation in Markdown
+
+```markdown
+
+```
diff --git a/creating-content/blocks/code-block.md b/creating-content/blocks/code-block.md
new file mode 100644
index 00000000..2dac3944
--- /dev/null
+++ b/creating-content/blocks/code-block.md
@@ -0,0 +1,123 @@
+---
+description: >-
+ Add a code block to a page to include sample code, configurations, code
+ snippets and more
+---
+
+# Code blocks
+
+You can add code to your GitBook pages using code blocks.
+
+When you add a code block, you can choose to [set the syntax](code-block.md#set-syntax...), [show line numbers](code-block.md#with-line-numbers), [show a caption](code-block.md#with-caption), and [wrap the lines](code-block.md#wrap-code). It’s also easy to [copy the contents of a code block to the clipboard](code-block.md#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!
+
+### 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](tabs.md) 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 %}
+
+{% hint style="info" %}
+You can make code blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
+{% endhint %}
+
+### 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](code-block.md#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.
+
+### 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 %}
+````
diff --git a/creating-content/blocks/columns.md b/creating-content/blocks/columns.md
new file mode 100644
index 00000000..cc41eb8e
--- /dev/null
+++ b/creating-content/blocks/columns.md
@@ -0,0 +1,40 @@
+---
+description: Add a column to create different layouts in your documentation.
+---
+
+# Columns
+
+Columns are a great way to create different layouts for your documentation. You can add many different types of blocks inside a column, and adjust the width of each side to customize it to the design you need.
+
+{% columns %}
+{% column width="50%" %}
+### Create a seamless experience between your docs and product
+
+Integrate your documentation right into your product experience, or give users a personalized experience that gives them what they need faster.
+
+Learn more
+{% endcolumn %}
+
+{% column %}
+
+{% endcolumn %}
+{% endcolumns %}
+
+## Representation in Markdown
+
+
## Example
+
+{% columns %}
+{% column width="50%" %}
+### Create a seamless experience between your docs and product
+
+Integrate your documentation right into your product experience, or give users a personalized experience that gives them what they need faster.
+
+<a href="https://www.gitbook.com/#alpha-waitlist" class="button primary">Learn more</a>
+{% endcolumn %}
+
+{% column %}
+<figure><img src="../../.gitbook/assets/GitBook vision post.png" alt="An image of GitBook icons demonstrating side by side column functionality"><figcaption></figcaption></figure>
+{% endcolumn %}
+{% endcolumns %}
+
diff --git a/creating-content/blocks/conditional-content.md b/creating-content/blocks/conditional-content.md
new file mode 100644
index 00000000..b8acad59
--- /dev/null
+++ b/creating-content/blocks/conditional-content.md
@@ -0,0 +1,45 @@
+# Conditional content
+
+Conditional content blocks let you control who can see a given block of content on your page based on user data and variables. These variables can be passed in via cookies, feature flags, authenticated access, or URL parameters.
+
+### Create conditional content
+
+To add a conditional block, begin a new line in the editor, type /, then select **Conditional content**.
+
+After inserting the block, click the red condition badge in the top right of the block.
+
+Clicking this will allow you to add a condition through the [condition editor](../../publishing-documentation/adaptive-content/adapting-your-content.md#working-with-the-condition-editor). You’ll be able to write your condition as an [expression](https://gitbook.com/docs/creating-content/variables-and-expressions) that will run against data defined in your site. You can reference data from [variables](../variables-and-expressions.md), or data coming from visitors through their [claims](../../publishing-documentation/adaptive-content/enabling-adaptive-content/#set-your-visitor-schema).
+
+See [adaptive content](../../publishing-documentation/adaptive-content/) for more details.
+
+### Example
+
+The examples below use a URL parameter linked from the button to control which conditional content block is visible.
+
+{% if visitor.claims.unsigned.example_attribute_A %}
+This block is only visible to users **with** attribute A.
+
+View without attribute A
+{% endif %}
+
+{% if !visitor.claims.unsigned.example_attribute_A %}
+This block is only visible to users **without** attribute A.
+
+View with attribute A
+{% endif %}
+
+## Representation in Markdown
+
+```markdown
+## Example
+
+{% if visitor.claims.unsigned.example_attribute_A %}
+This block is only visible to users **with** attribute A.
+View without attribute A
+{% endif %}
+
+{% if !visitor.claims.unsigned.example_attribute_A %}
+This block is only visible to users **without** attribute A.
+View with attribute A
+{% endif %}
+```
diff --git a/creating-content/blocks/drawing.md b/creating-content/blocks/drawing.md
new file mode 100644
index 00000000..9c5b0042
--- /dev/null
+++ b/creating-content/blocks/drawing.md
@@ -0,0 +1,31 @@
+---
+description: Create drawings within GitBook and add them to your page
+---
+
+# Drawings
+
+You can create a drawing or sketch directly though GitBook using the integrated [Excalidraw](https://excalidraw.com/) editor, then add it right into your GitBook page.
+
+To create a drawing, press `/` on an empty line to bring up the insert palette and choose **Drawing**. This will open a popover with Excalidraw tools — simply close the popover when you’re done and your diagram will appear on your GitBook page.
+
+GitBook stores drawings as special SVG files in the space. Those files have an extension of `drawing.svg`.
+
+### Example of a drawing block
+
+
+
+### Draw with GitBook AI
+
+{% include "../../.gitbook/includes/pro-and-enterprise-hint.md" %}
+
+When using drawing block, you can ask GitBook AI to generate an illustration by specifying a prompt. Simply type in a prompt and hit **Generate**, or choose one of the suggested prompts to get started.
+
+Once GitBook AI has finished the drawing, you can double-click to open the full drawing palette and edit it however you like.
+
+When editing a drawing, click the **Use AI to generate** button to bring up GitBook AI’s prompt editor again and generate a new drawing.
+
+### Representation in Markdown
+
+```markdown
+
+```
diff --git a/creating-content/blocks/embed-a-url.md b/creating-content/blocks/embed-a-url.md
new file mode 100644
index 00000000..6bcf6383
--- /dev/null
+++ b/creating-content/blocks/embed-a-url.md
@@ -0,0 +1,33 @@
+---
+description: Embed videos, music and more directly into your page with a URL
+---
+
+# Embedded URLs
+
+To add an embedbed URL, simply paste the link of the content you want to embed and hit `Enter`.
+
+{% hint style="info" %}
+**Note:** The content you want to embed must be publicly available in order for GitBook to access the file. For example, when embedding a Google doc the share settings must be set to _Anyone with the link_.
+{% endhint %}
+
+### Videos
+
+{% embed url="https://www.youtube.com/watch?v=D_uLM5i0Z4c" %}
+
+{% 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 %}
+
+### Codepen
+
+{% embed url="https://codepen.io/davidkpiano/pen/wMqXea" %}
+
+### Spotify
+
+{% embed url="https://open.spotify.com/track/4FmiciU3ZmfgABlbCSXcWw?si=65zMAhStT2ivTit-kZISWg" %}
+
+### Representation in Markdown
+
+```markdown
+{% embed url="URL_HERE" %}
+```
diff --git a/content-editor/blocks/expandable.md b/creating-content/blocks/expandable.md
similarity index 100%
rename from content-editor/blocks/expandable.md
rename to creating-content/blocks/expandable.md
diff --git a/creating-content/blocks/heading.md b/creating-content/blocks/heading.md
new file mode 100644
index 00000000..5782d146
--- /dev/null
+++ b/creating-content/blocks/heading.md
@@ -0,0 +1,52 @@
+---
+description: Add heading blocks to a page to organize your content and improve SEO
+---
+
+# Headings
+
+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](../../resources/gitbook-ui.md#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 GitBook space, you can use a [relative link](../formatting/inline.md#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](../../getting-started/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
+
diff --git a/creating-content/blocks/hint.md b/creating-content/blocks/hint.md
new file mode 100644
index 00000000..4b61966b
--- /dev/null
+++ b/creating-content/blocks/hint.md
@@ -0,0 +1,74 @@
+---
+description: >-
+ Add a hint to a page to draw your reader’s attention to specific pieces of
+ important information.
+---
+
+# Hints
+
+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 clicking the colored icon, or by opening the block’s **Options menu** and selecting the style you want.
+
+Hint blocks support [inline content](../formatting/inline.md) and [formatting](../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](./#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" %}
+#### 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" %}
+
+## 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 %}
+```
diff --git a/creating-content/blocks/insert-files.md b/creating-content/blocks/insert-files.md
new file mode 100644
index 00000000..5ab3476e
--- /dev/null
+++ b/creating-content/blocks/insert-files.md
@@ -0,0 +1,67 @@
+---
+description: Manage and add files to your space such as PDFs, videos, documents and more
+---
+
+# Files
+
+You can upload files to your GitBook space 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="../../.gitbook/assets/example.pdf" %}
+This is a caption on a file.
+{% endfile %}
+
+### Uploading a file
+
+You can manage uploaded files in the Files side panel of your space. You can find the Files panel at the top of your space’s table of contents.
+
+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 your space when you add an [image block](insert-images.md) or an [OpenAPI block](../../api-references/openapi/). When you create one of these blocks, the Files panel will open, 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 Files side panel for the respective space, 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 **Actions menu** for the file and click **Replace**. In the file replacement dialog that appears, select the new file and wait for the upload indicator to complete. Your file will automatically update everywhere it appeared in your space.
+
+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 space, 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 space by creating an image or a file block and selecting it from the **Files** side panel.
+
+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 %}
+```
diff --git a/creating-content/blocks/insert-images.md b/creating-content/blocks/insert-images.md
new file mode 100644
index 00000000..d7ff4fd6
--- /dev/null
+++ b/creating-content/blocks/insert-images.md
@@ -0,0 +1,163 @@
+---
+description: >-
+ 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
+---
+
+# Images
+
+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
+
+
+
+### 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](./#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 %}
+
+#### 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 **Actions 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 **Actions 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](cards.md).
+{% 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 **Actions 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 %}
+
+{% hint style="info" %}
+You can make image blocks [span the full width of your window](./#full-width-blocks) by clicking on the **Options menu** next to the block and choosing **Full width**.
+{% 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](insert-images.md#resizing).
+
+### Representation in Markdown
+
+```markdown
+//Simple Block
+
+
+//Block with Caption
+
+
+//Block with Alt text
+
+
+
+//Block with Caption and Alt text
+
+
GitBook Logo
+
+//Block with different image for dark and light mode, with caption
+
+
+
+
+
+
+ Caption text
+
+```
diff --git a/creating-content/blocks/math-and-tex.md b/creating-content/blocks/math-and-tex.md
new file mode 100644
index 00000000..55f901f9
--- /dev/null
+++ b/creating-content/blocks/math-and-tex.md
@@ -0,0 +1,29 @@
+---
+description: >-
+ Add a mathTeX block to a page when you want to display a mathematical formula
+ in your documentation
+---
+
+# Math & TeX
+
+You can use the mathTeX format to include mathematical formulae in your documentation. We offer this through the [KaTeX](https://katex.org/docs/supported.html) library.
+
+You can also add mathTeX [as inline content](../formatting/inline.md#math-and-tex).
+
+### Example of Math & TeX block
+
+$$
+s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
+$$
+
+
+
+### Representation in Markdown
+
+$$f(x) = x * e^{2 pi i \xi x}$$
+
+```markdown
+# Math and TeX block
+
+$$f(x) = x * e^{2 pi i \xi x}$$
+```
diff --git a/creating-content/blocks/ordered-list.md b/creating-content/blocks/ordered-list.md
new file mode 100644
index 00000000..bfa6c980
--- /dev/null
+++ b/creating-content/blocks/ordered-list.md
@@ -0,0 +1,45 @@
+---
+description: Add an ordered or numbered list to a page
+---
+
+# Ordered lists
+
+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
diff --git a/creating-content/blocks/page-link.md b/creating-content/blocks/page-link.md
new file mode 100644
index 00000000..4f96a369
--- /dev/null
+++ b/creating-content/blocks/page-link.md
@@ -0,0 +1,25 @@
+---
+description: Add a page link block to show relations between pages in your space.
+---
+
+# Page links
+
+Page link blocks are the best way create relations between different pages within your content. Page links stand out on the page as they fill their own block — compared to a hyperlink added to some text.
+
+### Example of page link block
+
+The links below point to [blocks](./) and [inline content](../formatting/inline.md):
+
+{% content-ref url="./" %}
+[.](./)
+{% endcontent-ref %}
+
+{% content-ref url="../formatting/inline.md" %}
+[inline.md](../formatting/inline.md)
+{% endcontent-ref %}
+
+## Representation in Markdown
+
+```markdown
+{% content-ref url="./" %} . {% endcontent-ref %}
+```
diff --git a/creating-content/blocks/paragraph.md b/creating-content/blocks/paragraph.md
new file mode 100644
index 00000000..212b127f
--- /dev/null
+++ b/creating-content/blocks/paragraph.md
@@ -0,0 +1,27 @@
+---
+description: Add a paragraph block to insert formatted text, inline images and more
+---
+
+# Paragraphs
+
+A paragraph is the most basic content block you can use on GitBook.
+
+{% hint style="info" %}
+You can [add other inline content](../formatting/inline.md) to your paragraph, such as emojis, images and Math & TeX.
+
+You can also [format your text](../formatting/) using the context menu or keyboard shortcuts, or using [Markdown](../formatting/markdown.md).
+{% 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 %}
diff --git a/creating-content/blocks/quote.md b/creating-content/blocks/quote.md
new file mode 100644
index 00000000..ba70a7f7
--- /dev/null
+++ b/creating-content/blocks/quote.md
@@ -0,0 +1,23 @@
+---
+description: >-
+ 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
+
+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](./#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 %}
diff --git a/creating-content/blocks/snippets.md b/creating-content/blocks/snippets.md
new file mode 100644
index 00000000..001b5249
--- /dev/null
+++ b/creating-content/blocks/snippets.md
@@ -0,0 +1,26 @@
+---
+description: >-
+ Add a snippet block to reference a specific snippet on your page, and
+ highlight it as important
+hidden: true
+---
+
+# Snippets
+
+{% hint style="warning" %}
+The Snippets feature is no longer maintained in GitBook and is subject to change. We recommend to structure your content a [space](../content-structure/space.md) instead.
+{% endhint %}
+
+Snippet blocks are a great way to reference a snippet in your content. Snippet blocks help make the link to your snippet stand out on the page compared to [an inline link](../formatting/inline.md#relative-links).
+
+You can only use snippet blocks for internal pages. If you add a snippet block to a page in a published space, the public documentation will show the block as a broken link.
+
+{% hint style="warning" %}
+**Note:** If you use a snippet block, but then [convert your snippet into a page](../../snippets/snippets-beta.md#convert-a-snippet-to-a-page) in your documentation, your snippet block will still link back to the original snippet, which will be archived.
+{% endhint %}
+
+### Representation in Markdown
+
+```
+{% content-ref url="./" %} . {% endcontent-ref %}
+```
diff --git a/content-editor/blocks/stepper.md b/creating-content/blocks/stepper.md
similarity index 91%
rename from content-editor/blocks/stepper.md
rename to creating-content/blocks/stepper.md
index 88c41ef6..14f2da9d 100644
--- a/content-editor/blocks/stepper.md
+++ b/creating-content/blocks/stepper.md
@@ -1,3 +1,7 @@
+---
+description: "Add a step-by-step guide to a page —\_perfect for guides, walkthroughs and technical troubleshooting processes"
+---
+
# Stepper
Stepper blocks let you break down a tutorial or guide into separate, but clearly linked steps. Each step can contain multiple different blocks, allowing you to add detailed information.
diff --git a/creating-content/blocks/table.md b/creating-content/blocks/table.md
new file mode 100644
index 00000000..34f17fbe
--- /dev/null
+++ b/creating-content/blocks/table.md
@@ -0,0 +1,79 @@
+---
+description: Keep information organized and make documenting data easier with tables
+---
+
+# Tables
+
+You can add tables to better organize your information in a GitBook page.
+
+
+
+### Table block options
+
+When you open the Options menu to the left of a table block, you’ll have a number of options to change the appearance and manage the data inside the table:
+
+* **Table/Cards:** Choose to display your data as either a table block or [a cards block](cards.md). GitBook populates both these blocks using the same data, so you can switch between them depending on the look and design you want.
+* **Add column:** Add a new column to the right of your table. You can choose column type using the menu, or just click **Add column** to add a text column.
+* **Insert row:** Add a new row to the bottom of your table.
+* **Show header:** Hide or show the top totle row of your table. Depending on the data you’re display, you may not need a title row in your table, so you can disable it here.
+* **Reset column sizing:** If you’ve changed the column widths, this will reset them all to be equal again.
+* **Visible columns:** Choose which columns are visible and which are hidden. If you have hidden columns in your table, this menu is where you can make them visible again.
+* **Full width:** Make your table span the full width of your window. This is great for tables with lots of columns.
+* **Delete:** Deletes the table block and all of it’s content.
+
+### Changing a column type
+
+Depending on the data you want to display, you can set table columns can have different data types. These add formatting, embellishments or restrictions to every cell in the column:
+
+* **Text:** A standard text column, with standard formatting support.
+* **Number:** A number column, with or without floating digits.
+* **Checkbox:** A checkbox on each line that can be checked or unchecked.
+* **Select:** You can select data from a list of options that you can define by opening the **Columns options** menu and choosing **Manage options**. This can be single-choice or multiple-choice.
+* **Users:** You can add the name and avatar of a member of your organization. This can be single-choice or multiple-choice.
+* **Files:** You can reference a file in the space. You can upload new files when populating cells in the column.
+* **Rating:** A star rating. You can configure the maximum rating by opening the **Column options** menu and choosing **Max**.
+
+Use the **Column options** menu to change a column’s type. When you change a column type, you’ll see a prompt asking you to confirm the change, as column data could be deleted or broken by this action.
+
+### Resizing columns
+
+Hover over a column’s edge and drag to resize it. A pixel count appears above the cursor to help you set consistent column sizes.
+
+GitBook stores column sizes as a percentage of the overall width, which allows for relative sizing based on the overall width of the table.
+
+### Scrolling tables
+
+Tables that are wider than the editor container will be horizontally scrollable.
+
+### Column options
+
+To reorder columns, click and drag on the drag handle at the top of the column you want to move.
+
+You can add new columns by clicking the **Add column** button that appears when you hover over the right edge of the table.
+
+Inside the **Column options** menu you can also switch automatic sizing on and off, add a new column to the right, hide the column, or delete the column.
+
+### Row options
+
+Hover over the row and click the **Row options** button that appears on the left of it to open the **Row options** menu. You’ll see a number of options:
+
+* **Open row:** Open the row in a modal that shows all of its data. Here you can quickly change row types, edit data, and see data in hidden columns.
+* **Insert above/below:** Add a new row above or below the currently-selected row.
+* **Add column:** Add a new column on the right of the table.
+* **Delete row:** Permanently remove all the data in the row from your table.
+
+### Images in tables
+
+When you click into a table cell, you can hit the / key to insert images. This will not work in the header row.
+
+### Representation in Markdown
+
+```markdown
+# Table
+
+| | | |
+| - | - | - |
+| | | |
+| | | |
+| | | |
+```
diff --git a/creating-content/blocks/tabs.md b/creating-content/blocks/tabs.md
new file mode 100644
index 00000000..712d23ae
--- /dev/null
+++ b/creating-content/blocks/tabs.md
@@ -0,0 +1,47 @@
+---
+description: >-
+ Add tabs so you can display large blocks of related information without
+ creating a long, hard-to-navigate page
+---
+
+# Tabs
+
+A tab block is a single block with the option to add multiple tabs.
+
+Each tab can contain multiple other blocks, of any type. So you can add code blocks, images, integration blocks and more to individual tabs in the same tab block.
+
+### Add or delete tabs
+
+To add a new tab to a tab block, hover over the edge of a tab and click the `+` button that appears. To delete a tab, open the tab’s **Options menu** then select **Delete**.
+
+### Example
+
+Here is an example that lists instructions relevant to specific platforms:
+
+{% tabs %}
+{% tab title="Windows" %}
+Here are the instructions for Windows
+{% endtab %}
+
+{% tab title="macOS" %}
+Here are the instructions for macOS
+{% endtab %}
+
+{% tab title="Linux" %}
+Here are the instructions for Linux
+{% endtab %}
+{% endtabs %}
+
+### Representation in Markdown
+
+```markdown
+{% tabs %}
+
+{% tab title="Windows" %} Here are the instructions for Windows {% endtab %}
+
+{% tab title="OSX" %} Here are the instructions for macOS {% endtab %}
+
+{% tab title="Linux" %} Here are the instructions for Linux {% endtab %}
+
+{% endtabs %}
+```
diff --git a/creating-content/blocks/task-list.md b/creating-content/blocks/task-list.md
new file mode 100644
index 00000000..2b8f74d1
--- /dev/null
+++ b/creating-content/blocks/task-list.md
@@ -0,0 +1,27 @@
+---
+description: Add a task list to display tasks that can be completed
+---
+
+# Task lists
+
+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 space will not be able to 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
+ * [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`.
+
+### 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, unidented using `shift` + `tab`.
+```
diff --git a/creating-content/blocks/unordered-list.md b/creating-content/blocks/unordered-list.md
new file mode 100644
index 00000000..09114383
--- /dev/null
+++ b/creating-content/blocks/unordered-list.md
@@ -0,0 +1,33 @@
+---
+description: Add an unordered list block to create bullet point lists
+---
+
+# Unordered 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
+```
diff --git a/creating-content/broken-links.md b/creating-content/broken-links.md
new file mode 100644
index 00000000..ddd709be
--- /dev/null
+++ b/creating-content/broken-links.md
@@ -0,0 +1,42 @@
+---
+description: Find and replace broken relative links across your spaces
+hidden: true
+noIndex: true
+icon: link-slash
+---
+
+# Broken links
+
+{% include "../.gitbook/includes/pro-and-enterprise-hint.md" %}
+
+
The Broken links panel that you can open on the right of a space to check for broken internal links.
+
+You can add different [types of links](formatting/inline.md#links) to your pages in GitBook. If someone has broken a [relative link](formatting/inline.md#relative-links) while making a change request by updating it or changing its location, you’ll see a notification letting you know there’s something to fix.
+
+{% hint style="info" %}
+Broken link detection currently works only for relative links to other GitBook content in your organization. It will not detect broken links to external URLs.
+{% endhint %}
+
+To view broken links, click the broken link symbol in the [space header](../resources/gitbook-ui.md#space-header) when inside a change request.
+
+### Fix a broken link
+
+If GitBook finds a broken link, you’ll see a notification in this section with a link to the page that includes the broken link. Then, simply replace or update the link with a valid one.
+
+As you view your broken links, you can also set the scope and filter of broken links inside of the sidebar:
+
+#### Scope: Current change request
+
+This will find newly broken links within the scope of the current change request you are working in.
+
+#### Scope: Current space
+
+This will find broken links within the scope of the current space you are in.
+
+#### Filter by: Broken links
+
+Show any broken or missing links in the space or change request you are in.
+
+#### Filter by: Internal links
+
+This filter is useful for making sure your published docs don’t link to internal content within your GitBook organization. It’ll show any links to internal, unpublished content that readers of your published content won’t have access to (i.e. links that start `app.gitbook.com/o//…`). You can fix them by replacing the links with the URL of the published GitBook page.
diff --git a/creating-content/content-structure/README.md b/creating-content/content-structure/README.md
new file mode 100644
index 00000000..02b3d4a6
--- /dev/null
+++ b/creating-content/content-structure/README.md
@@ -0,0 +1,10 @@
+---
+description: Create pages, spaces and collections
+icon: folder-tree
+---
+
+# Content structure
+
+The structure of your content in GitBook is organized through pages, spaces and collections. Pages live inside of spaces, and collections are groups of spaces.
+
+
Cover image (dark)
Cover image
Spaces
Create a space to organize your documentation in one place.
diff --git a/creating-content/content-structure/collection.md b/creating-content/content-structure/collection.md
new file mode 100644
index 00000000..f5edfc27
--- /dev/null
+++ b/creating-content/content-structure/collection.md
@@ -0,0 +1,36 @@
+---
+description: Organize your spaces into folders.
+---
+
+# Collections
+
+Collections are a way to group spaces together to make it easier for you to organize your content. With collections, you can:
+
+* organize your content by similar topics or ideas
+* manage space [permissions](../../account-management/member-management/permissions-and-inheritance.md) at scale by allowing you to override the organization-level defaults.
+
+### Create a collection
+
+Click the **+** button next to the **Spaces** header in the sidebar to create a new collection. You can also create a collection or space within another collection from the collection’s main page.
+
+### Move a collection
+
+You can move a collection by opening the **Actions menu** , selecting **Move collection to…** and choosing a destination. Alternatively, you can drag and drop collections in the sidebar to move or reorder them.\
+\
+You can move collections into other collections — or even to other organizations, if you have an [admin role](../../account-management/member-management/roles.md) in both.
+
+### Nested collections
+
+You can nest collections inside each other, creating a collection -> sub-collection -> space hierarchy.
+
+Open a collection and you can click **New collection** from the collection’s main page to create a sub-collection.
+
+To move one collection into another, click **Move collection to…** from the collection’s **Action menu** and then choose its new location. Alternatively, you can drag and drop the collection to its new location.
+
+### How to delete a collection
+
+You can delete a collection by opening its **Actions menu** and selecting **Delete**.
+
+{% hint style="danger" %}
+**Deleting a collection is final**, but spaces inside a deleted collection will move to the **Trash** and can be restored up to seven days after deletion. You can access the Trash from the bottom of the sidebar.
+{% endhint %}
diff --git a/creating-content/content-structure/page.md b/creating-content/content-structure/page.md
new file mode 100644
index 00000000..c426ce22
--- /dev/null
+++ b/creating-content/content-structure/page.md
@@ -0,0 +1,118 @@
+---
+description: "Add pages, page groups or external links —\_and learn about the options you have on each page"
+---
+
+# Pages
+
+A page is the place where you can add, edit and embed content. Pages always live inside a [space](space.md), allowing you to group related content and create different sections for the topics or areas you’re covering.
+
+When publishing your documentation, each space will be its own [docs site](../../publishing-documentation/publish-a-docs-site/) or [site section](../../publishing-documentation/site-structure/site-sections.md), and the pages inside the space will all appear on that site.
+
+### Table of contents
+
+You can create as many pages as you need in a space. They’re all visible on the left sidebar of your screen in your space’s [table of contents](../../resources/gitbook-ui.md#table-of-contents). The table of content will appear in the same place when you publish your space, unless [you choose to hide it](page.md#page-options).
+
+### Create a new page
+
+When in [live edit](../../collaboration/live-edits.md) mode or in a [change request](../../collaboration/change-requests.md), you can create a new page by clicking **Add new...** > **Page** at the bottom of your table of contents. Alternatively, you can 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.
+
+### Can’t see the option to create a new page?
+
+{% hint style="warning" %}
+If [live edits](../../collaboration/live-edits.md) are disabled for your space, you’ll need to create or edit a [change request](../../collaboration/change-requests.md). Once you’re in a change request, the **New page** button (which allows you to create pages, page groups and links) will be available in the table of contents.
+
+Alternatively, you may not have the correct [permissions](../../account-management/member-management/permissions-and-inheritance.md) 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, and optional description, and an area where you can write and add any kind of content.
+
+You can nest pages by dragging and dropping a page below an other in the table of contents. Doing this creates a **subpage**.
+
+If you add subpages to an empty parent page, GitBook will automatically generate 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 we’d recommend you avoid more than three levels of nesting to avoid an overly-complex navigation.
+{% endhint %}
+
+When you change the title of a page, the page’s slug (the part at the very end of the URL, e.g. `/hello-world`) will also change — unless you’ve manually set the page’s slug previously.
+
+You can change the title and the slug of a page at any time by clicking opening the page’s **Action menu** and choosing **Rename**.
+
+#### Page groups
+
+With page groups, you can bring pages together into sections that cover related content.
+
+You can create a new page group by clicking **Add new...** > **Group** at the bottom of your table of contents.
+
+Page groups can only live at the **top level** of the table of contents. You cannot nest page groups inside page groups.
+
+To change the title and slug of a page group, click the **Action menu** icon next to the group title in the table of contents and choose **Rename**.
+
+#### External links
+
+You can also add links to your table of contents. Clicking them will take people directly to the linked content.
+
+Create new 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, you can add an optional icon or emoji to individual pages. The icon or emoji will appear 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 you can customize the look and feel of a selected page within a space, and control its visibility.
+
+**Layout**
+
+You can open the **Page options** menu or change a page’s cover by hovering over the page title. You’ll see the buttons appear just above the page title.
+
+In the **Page options** side panel, you can select how each page is displayed to those who visit your **published** content. There are three layout presets to choose from, or you can create a custom layout.
+
+Each layout preset will toggle on or off each of the following parts of the page:
+
+* Page title
+* Page description
+* Table of contents
+* Page outline
+* Next/previous links
+* Page metadata
+
+You can also set your page’s global width from this menu. Choosing **Wide** will automatically widen blocks that support the **Full width** option — such as tables, cards and code blocks — to give them more space when the page is published. Which is ideal for creating eye-catching landing pages!
+
+#### Visibility
+
+You can decide which pages you would like to show/hide in your published documentation, while also deciding if you would like the page to be indexed in your published doc’s search, and/or indexed by search engines.
+
+You can hide a page or group of pages from your site's table of contents by opening the page’s **Actions menu** and toggling **Hide page**.
+
+If hidden the following will appear in the front matter of the markdown file when using Git Sync:
+
+
---
+hidden: true
+---
+
+
+### Page covers
+
+You can also set a page cover for each page of your documentation. When you click the **Page cover** option, a default cover will be added immediately. From here, you can:
+
+* **Change the cover image**
+
+ Hover over the page cover and click **Change cover**, then select or upload an image. Based on how we currently display page covers, 1990x480 pixels is the ideal size.
+* **Reposition the cover image**
+
+ Hover over the page cover and open the **Actions menu** . Click **Reposition**, then drag the image as you wish and click **Save**.
+* **Remove the cover image**\
+ Hover over the page cover and open the **Actions menu** , then click **Remove**.
+* **Full width and hero width**\
+ You can change the style of your page cover to span the full width of your screen or just the width of your content. Hover over the page cover and open the **Actions menu** , then choose your preferred option from the menu.
diff --git a/creating-content/content-structure/space.md b/creating-content/content-structure/space.md
new file mode 100644
index 00000000..21875cdb
--- /dev/null
+++ b/creating-content/content-structure/space.md
@@ -0,0 +1,35 @@
+---
+description: Organize the content you create and publish into spaces
+---
+
+# Spaces
+
+A space is a project that lets you work on a collection of related pages. They allow you to write content, organize pages, add integrations and more.
+
+
+
+### Create a space
+
+Click the **+** button next to the **Spaces** header in the sidebar and choose **New space** to create a new space. You can also create a new space inside a [collection](collection.md).
+
+You can edit a space’s name by hovering over the name in the [space header](../../resources/gitbook-ui.md#space-header).
+
+### Duplicate a space
+
+To duplicate a space, open that space's **Action menu** in the sidebar and select **Duplicate**.
+
+Duplicating a space will create a copy of the source space, in the same location (organization, collection, sub-collection, etc.).
+
+### Move a space
+
+You can move a space by opening the space’s **Action menu** in the sidebar, selecting **Move space to…** and choosing a destination. Alternatively, you can drag and drop spaces in the sidebar to move or reorder them.\
+\
+You can move spaces between collections within the same organization, as long as you have an [admin role](../../account-management/member-management/roles.md).
+
+### Delete a space
+
+You can delete a space by opening the space’s **Action menu** in the sidebar and selecting **Delete**.
+
+{% hint style="warning" %}
+**Deleted spaces can be restored from the Trash for up to 7 days**. After this, they will be permanently deleted.
+{% endhint %}
diff --git a/creating-content/formatting/README.md b/creating-content/formatting/README.md
new file mode 100644
index 00000000..f7e16dfa
--- /dev/null
+++ b/creating-content/formatting/README.md
@@ -0,0 +1,84 @@
+---
+description: >-
+ Format your content in various ways using the context menu or keyboard
+ shortcuts
+icon: i-cursor
+---
+
+# Formatting your content
+
+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](../../resources/keyboard-shortcuts.md) 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 space, we recommend [using a relative link](inline.md#relative-links).
+
+This is [a link to an external page](https://www.gitbook.com).
+
+This is a [link to another page in this space](../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.
diff --git a/creating-content/formatting/inline.md b/creating-content/formatting/inline.md
new file mode 100644
index 00000000..a5ac0152
--- /dev/null
+++ b/creating-content/formatting/inline.md
@@ -0,0 +1,177 @@
+---
+description: Use the inline palette to add images, links, math & TeX, and more
+---
+
+# Inline content
+
+
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.
+
+```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.
+```
+
+### 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](../blocks/insert-images.md), which is as wide as your content.
+
+{% hint style="info" %}
+[Image blocks](../blocks/insert-images.md) 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 %}
+
+### 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:
+:car:
+:dog:
+```
+{% endcode %}
+
+### Links
+
+You can insert three different types of links:
+
+* [Relative links](inline.md#relative-links)
+* [Absolute links](inline.md#absolute-links)
+* [Email address `mailto` links](inline.md#email-address-mailto-links)
+
+#### Relative links
+
+Relative links are links created by linking to [pages](../content-structure/page.md) that already exist in your space. 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 space](../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
+```
+
+### Math & TeX
+
+Using this option, you can create an inline math formula in your content, like this: $$f(x) = x * e^{2 pi i \xi x}$$. 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](../blocks/math-and-tex.md) by opening the command palette in an empty block and choosing the second Math & TeX option.
+{% endhint %}
+
+#### Representation in Markdown
+
+```markdown
+# Math and TeX block
+
+$$f(x) = x * e^{2 pi i \xi x}$$
+```
+
+### Buttons
+
+Buttons are a great way to describe calls to action. You can use them to send users to other pages in GitBook, or to external URLs.
+
+Buttons have both primary and secondary styles. Here are a couple of examples:
+
+Sign up to GitBookGo to top
+
+#### Representation in Markdown
+
+```markdown
+GitBook
+```
+
+### Icons
+
+Icons allow you to add extra visual indications to your site. You can add them inline to paragraphs, inside a card, or anywhere else you need to add some flair. They will use the visual style defined in your [customization settings](../../publishing-documentation/customization/icons-colors-and-themes.md).
+
+:facebook::github::x-twitter::instagram:
+
+Visit [Font Awesome](https://fontawesome.com/) to explore the different icons available.
+
+#### Representation in Markdown
+
+```markdown
+:github:
+```
+
+### Expressions
+
+Expressions allow you to dynamically display content defined in a [variable](../variables-and-expressions.md). Expressions can be inserted from the `/` menu. Once inserted, double 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.
diff --git a/creating-content/formatting/markdown.md b/creating-content/formatting/markdown.md
new file mode 100644
index 00000000..0a21be37
--- /dev/null
+++ b/creating-content/formatting/markdown.md
@@ -0,0 +1,70 @@
+---
+description: >-
+ Write Markdown directly in the editor to easily create content using common
+ syntax
+---
+
+# Markdown
+
+
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` |
+
+### 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.
+
+{% 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 %}
+
+### 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.
+
+{% hint style="info" %}
+When writing any kind of list, hit `Tab` to add a indent, and `Shift+Tab` to outdent.
+{% endhint %}
+
+### 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.
diff --git a/creating-content/reusable-content.md b/creating-content/reusable-content.md
new file mode 100644
index 00000000..16165dad
--- /dev/null
+++ b/creating-content/reusable-content.md
@@ -0,0 +1,90 @@
+---
+description: >-
+ Create reusable blocks of content that can be used across spaces, and all
+ updated at once when you change an instance
+icon: repeat
+---
+
+# Reusable content
+
+{% include "../.gitbook/includes/pro-and-enterprise-hint.md" %}
+
+Reusable content lets you sync content across multiple pages and spaces, so you can edit all instances of the block at the same time.
+
+
Create reusable content within a space.
+
+## Fundamentals
+
+Reusable content works just like any other content—you can modify it via change requests, include it in review workflows, and it will render correctly on any published site.
+
+While reusable content can be referenced across multiple spaces, it belongs to a single _parent space_.
+
+### The "parent space" concept
+
+The parent space is the space that owns the reusable content. It’s the only place where that content can be edited.
+
+Even though updates to reusable content will appear instantly in all instances, all changes must originate from the parent space—either as a direct edit or through a change request.
+
+Spaces are a core concept in GitBook, supporting both editorial workflows and security. Because GitBook enforces permission-based editing, reusable content can only be changed from its parent space. This ensures that editing rights are respected, even when the content is reused across the organization.
+
+### Known limitations
+
+#### Integrations
+
+Blocks provided by integrations are not supported in reusable content. This is because integrations in GitBook are installed per space, and limiting access ensures that third-party integrations only have the permissions you grant. Referencing reusable content across spaces would break this security boundary.
+
+#### Search
+
+Currently, reusable content only appears in search results within its parent space. We’re actively working to remove this limitation so that reusable content shows up in search results wherever it’s referenced.
+
+## In the app
+
+### **Create reusable content**
+
+To create reusable content, [select one or more blocks](blocks/#selecting-blocks-and-interacting-with-selected-blocks), then open the **Actions menu** , select **Turn into**, and choose **Reusable content**. You can also give your block a name to make it easier to find and reuse later.
+
+Alternatively, you can select one or more blocks and then hit **Cmd + C** to open a prompt asking if you want to create reusable content.
+
+### **Insert reusable content**
+
+You can insert reusable content as you would with any other block. Hit `/` on an empty line to open the **Insert palette** and search for your content by its name or simply searching for “reusable”. Alternatively, click the `+` on the left of any block or empty line.
+
+You will also find the reusable content panel in the pages sidebar, where you can find a list of previously created content blocks in your current space.
+
+### **Edit reusable content**
+
+Reusable content is like any other content — you can edit any instance directly if [live edits](../collaboration/live-edits.md) are enabled, or through [a change request](../collaboration/change-requests.md) if not. Any changes you make will be synced everywhere the content is used.
+
+If you’re making changes inside a change request, the content will be synced to all other instances once that change request is merged.
+
+### **Detach reusable content**
+
+You can detach reusable content by opening the **Actions menu** and selecting **Detach**. Detaching will convert the content back to regular blocks.
+
+Once detached, any changes you make to the block(s) will not be reflected across the other instances, and changes you make in those instances will not be reflected in the detached block(s). All other instances of the reusable content remain synced together.
+
+### Delete reusable content
+
+You can delete reusable content from your space entirely, if you wish. Find the reusable content in the page’s table of contents, then open the **Actions menu** next to the content you’d like to delete, and select **Delete**.
+
+Deleting reusable content will **delete it from all pages it is used in**. This action cannot be undone.
+
+## Syncing with GitHub & GitLab
+
+Reusable content is fully supported when syncing to GitHub & GitLab. Your reusable content will be exported to a dedicated `includes` folder, each content being a separate Markdown file.
+
+Your content is then referenced in your other pages using the `includes` directive.
+
+{% hint style="info" %}
+When syncing, the `.gitbook/includes` directory is created in the root of each synced space (which may not be the root of the whole repository). If your `.gitbook/includes` folder or its files appear in your space’s table of contents, you may need to hide them manually from the TOC.
+{% endhint %}
+
+#### Example
+
+{% hint style="success" %}
+If you're writing on the GitHub side, ensure the path to the include is relative to the file containing the reference (not the root of the repository).
+{% endhint %}
+
+```markdown
+{% include "../../.gitbook/includes/reusable-block.md" %}
+```
diff --git a/creating-content/searching-your-content/README.md b/creating-content/searching-your-content/README.md
new file mode 100644
index 00000000..83ce6e9e
--- /dev/null
+++ b/creating-content/searching-your-content/README.md
@@ -0,0 +1,20 @@
+---
+description: >-
+ Find what you’re looking for faster with keyword search and AI-powered smart
+ search
+icon: magnifying-glass
+---
+
+# Searching content
+
+
Ask questions or search through your content using the built in search bar.
+
+Whether you’re working within the GitBook app or your visitors are reading your published content, GitBook’s search functions help to make it easy to find what you’re looking for.
+
+You can use quick find to look for specific words or phrases, or you can ask GitBook AI a question. It’ll scan through your docs and summarize an answer in seconds, with references to help you find out more.
+
+{% hint style="success" %}
+### Global search
+
+If you’re publishing your documentation on [an Ultimate site plan](../../account-management/plans/#site-plans), and add multiple spaces as [site sections](../../publishing-documentation/site-structure/site-sections.md), your users will be able to use the **Ask or search** bar to find information across all your site sections.
+{% endhint %}
diff --git a/creating-content/searching-your-content/gitbook-ai.md b/creating-content/searching-your-content/gitbook-ai.md
new file mode 100644
index 00000000..da9fa87d
--- /dev/null
+++ b/creating-content/searching-your-content/gitbook-ai.md
@@ -0,0 +1,39 @@
+---
+description: >-
+ GitBook uses AI to help you find the knowledge you need within your
+ organization, faster
+---
+
+# GitBook AI
+
+When engaging with GitBook AI, you have the ability to ask questions or elaborate on specific requirements. This AI-driven tool is designed to review your documentation in real-time, providing you with quick, direct answers.
+
+{% hint style="info" %}
+GitBook AI search is available both within the GitBook app to search internal content, and [in published content to search that specific docs site](../../publishing-documentation/search-and-gitbook-assistant.md).
+{% endhint %}
+
+## GitBook AI helps you find answers in the GitBook app
+
+{% include "../../.gitbook/includes/pro-and-enterprise-hint.md" %}
+
+You can enable GitBook AI for your organization’s internal content, allowing you to ask questions and get semantic answers about your internal knowledge base.
+
+Head to the **Organization settings** page and, in the **General** tab, toggle the **Enable GitBook AI** setting on.
+
+### Using GitBook AI search
+
+Once GitBook AI is enabled, open the **Ask or search** menu from the left sidebar and simply type out a question. GitBook AI will take a few seconds to scan your documentation and summarize the results.
+
+### FAQs
+
+#### How long does it take for GitBook AI to index changes?
+
+When someone makes a change to your content — such as a merged [change request](../../collaboration/change-requests.md) — it can take **up to one hour** for GitBook to index the changes to and reflect them in AI search results.
+
+#### How does GitBook AI handle my data?
+
+We pass your content to OpenAI to index and process data. OpenAI **does not** use this content for service improvements (including model training). You can find out more about how OpenAI handles data [here](https://openai.com/blog/introducing-chatgpt-and-whisper-apis#developer-focus).
+
+#### How do I prevent hallucinations with GitBook AI search?
+
+If you’re seeing GitBook produce answers that are incorrect, the best method for correcting this is write explicit content around the topic so the AI does not have to guess.
diff --git a/creating-content/searching-your-content/quick-find.md b/creating-content/searching-your-content/quick-find.md
new file mode 100644
index 00000000..e397f181
--- /dev/null
+++ b/creating-content/searching-your-content/quick-find.md
@@ -0,0 +1,31 @@
+---
+description: Search and navigate your documentation fast with quick find.
+---
+
+# Search & Quick find
+
+GitBook’s **Quick find** palette lets you search for content across all your organizations, and jump between them fast.
+
+### Use Quick find
+
+****You can open the **Quick find** palette by hitting the **Quick find** button at the top of the sidebar or by pressing **⌘ + K** on Mac or **Ctrl + K** on PC.
+
+### Search results
+
+Results from the space you’re currently in appear at the top, followed by results from other spaces from the organization you’re currently working in — **as well as other organizations** you are a member of.
+
+When you select a search result from an organization, you’ll switch to browsing that organization. To go back, use quick find to select a document in the organization you were in before, or use [the organization switcher](../../resources/gitbook-ui.md#the-sidebar) in the sidebar.
+
+{% hint style="info" %}
+We do not currently support the ability to prioritize certain content in Quick find results.
+{% endhint %}
+
+### Permissions
+
+**Quick find** is compliant with your team’s permission settings, meaning that users will only be able to search the content they have permission to access.
+
+### Content indexing
+
+We index your content by grouping it into sections. Sections are denoted using [H1, H2 or H3 Headings](../blocks/heading.md), with the content that follows them forming part a section.
+
+Each result shows the first three lines of information below the section header. If your section is too big, your keyword match may not appear in the preview — but don’t worry, quick find still found a match!
diff --git a/creating-content/translations.md b/creating-content/translations.md
new file mode 100644
index 00000000..60d34ab5
--- /dev/null
+++ b/creating-content/translations.md
@@ -0,0 +1,121 @@
+---
+description: >-
+ Auto-translate your content into multiple languages using AI and keep it
+ synced.
+icon: language
+---
+
+# Translations
+
+{% hint style="warning" %}
+Auto translations are currently in Beta. Let us know if you have any feedback or encounter any issues.
+{% endhint %}
+
+Auto translations make it easy to keep your documentation up-to-date in multiple languages, with minimal manual effort. You can create a space as a translation of another, and let AI handle the rest.
+
+
+
+## How translations work
+
+* **Create a translation space:** Set up a new space as a translation of an existing one. Choose your source space and target language.
+* **Continuous updates:** Every time you make changes to the source content, the translation workflow only runs for the **pages that have been changed**.
+* **Automatic sync:** After changes are merged, the translation workflow **runs automatically** and syncs with its source, so your translated space always reflects the latest updates.
+
+## Set up an auto translation
+
+To translate a space to a new language, start by creating a new [space](content-structure/space.md#create-a-space) in your organization. From the modal that appears, click “Translation” from the quick actions menu.
+
+From the modal that appears, you’ll need to choose a:
+
+* Source
+* Source language
+* Target language
+
+These options will be used to translate your space into a duplicated, translated space in your organization. You’ll also see a quick overview on the cost of translating your space.
+
+### Advanced configuration
+
+**Custom AI instructions:** Add advanced instructions to guide the AI on tone of voice, style, or other preferences. This helps ensure your translations match your brand or audience.
+
+{% hint style="info" %}
+Adding custom instructions to your translation workflow can be helpful, but is limited in certain cases.
+
+Custom instructions cannot be used to create new elements on a translated space, add extra text, or change the structure of the source content.
+{% endhint %}
+
+**Glossary support:** Define a glossary to control how specific terms are translated. This keeps terminology consistent across all supported languages.
+
+{% hint style="warning" %}
+**Changing your glossary will trigger a full re-translation of your content**. There is currently no workaround: we cannot reliably detect which pages might contain a glossary keyword, so the safest approach is to re-translate all pages. Updating the glossary may therefore be time- and cost-intensive.
+{% endhint %}
+
+## Add a translation to a variant
+
+After creating a translation, you’ll be able to add it to published docs site as a [variant](../publishing-documentation/site-structure/variants.md). This will allow users to toggle between languages in the upper right corner when viewing your main docs site.
+
+{% hint style="info" %}
+To provide the best experience for your users, you’re able to set the default language of a variant when setting it in your settings.
+
+It’s best practice to add the language of your translated space when setting up your variant.
+{% endhint %}
+
+Head to your site settings, under the structure tab to set up a new variant for any translations you have.
+
+## Pricing
+
+Translations are a paying **monthly** add-on:
+
+* $25 for up to 50,000 translated words
+* $0.20 per additional 1,000 words
+
+Each month includes 50,000 words of translation for $25. After that, every additional 1,000 words costs $0.20. Your 50,000-word allowance resets at the start of each month.
+
+In your first translation, every word will count towards your bill. After that, only new or updated words are charged. For example, if you edit your docs later, only the new words in the changed text will count towards your word limit — you won’t be re-billed for the entire document.
+
+## FAQ
+
+
+
+Why use auto-translations?
+
+* **Effortless multilingual docs:** Reach a global audience without manual translation work.
+* **Smart updates:** Only changed pages are re-translated, saving time and resources.
+* **Full control:** Customize translations with advanced instructions and glossary management.
+
+
+
+
+
+Can I edit the translation?
+
+You currently can't edit translations.
+
+As translations are done as a pure transformation of the source content, we can't reconcile potential edits made on the translation result with a new translation.
+
+To workaround it, we recommend the following flow:
+
+* Use the glossary to define specific translations that you want the AI to use
+* Use the custom instructions to iterate on the output
+
+
+
+
+
+How many translations do I need to create?
+
+You should only create **one translation workflow per language** of any given source content. Creating multiple workflows will accrue extra, duplicated costs in your organization.
+
+
+
+
+
+What are some current limitations?
+
+* Translations do not localize UI elements in your variant automatically. Head to your site’s customization settings to [localize the interface](../publishing-documentation/customization/extra-configuration.md#localize-user-interface) for a [specific variant](../publishing-documentation/customization/#customizing-sites-with-multiple-sections).
+ * This includes user-input customizations, such as announcement banners.
+* Translations cannot add extra content to the page - like a hint or a banner noting that a page was translated by AI. Consider adding an extra page in the translated space to note this, or the [announcement banner](../publishing-documentation/customization/layout-and-structure.md#announcement-premium-and-ultimate) in your site variant.
+* Changing the glossary triggers a full re-translation of all pages, which can increase processing time and cost. There is no partial re-translation based on glossary usage at this time.
+
+
+
+If you need help getting started or want to learn more about configuring auto-translations, [contact our support team](https://gitbook.com/docs/help-center/further-help/how-do-i-contact-support).
diff --git a/creating-content/variables-and-expressions.md b/creating-content/variables-and-expressions.md
new file mode 100644
index 00000000..29aeac77
--- /dev/null
+++ b/creating-content/variables-and-expressions.md
@@ -0,0 +1,40 @@
+---
+description: Create reusable variables that can be referenced in pages and spaces
+icon: icons
+---
+
+# Variables and expressions
+
+With variables you can create reusable text that can be conditionally referenced in [expressions](formatting/inline.md#expressions) and [conditions for adaptive content](../publishing-documentation/adaptive-content/adapting-your-content.md#working-with-the-condition-editor).
+
+If you repeat the same name, phrase or version number multiple times within your content, you can create a **variable** to help keep all those instances in sync and accurate — which is useful if you ever need to update them, or they’re complex and often mistyped.
+
+You can create variables that are scoped to a single page, or a single space.
+
+### Create a new variable
+
+To create a new variable, Click the **Variables** icon in the upper right corner when editing an open [change request](../collaboration/change-requests.md). This will open the Variables side panel.
+
+You can use the toggle at the top to view and create variables scoped either to the current page you’re on, or all pages within the current space.
+
+Clicking **Create a variable** will launch a modal where you can give your variable a name and a value.
+
+Click **Add variable** to save your variable.
+
+
You can add variables to a single page or an entire space. When you update the value of a variable, every instance of it will update.
+
+{% hint style="info" %}
+Variable names must start with a letter, and can contain letters, numbers and underscores.
+{% endhint %}
+
+### Use variables in your content
+
+Variables can be referenced and used within an [expression](formatting/inline.md#expressions) — which you can insert into your content inline. After inserting an expression, double click it to open the expression editor.
+
+Variables defined under your page are accessible under the `page.vars` object. Similarly, variables defined across your entire space are accessible under the `space.vars` object.
+
+
You can add variables to your content within expresions. The expression editor offers autocomplete options to help you find the variable you need.
+
+### Update a variable
+
+You can update a variable at any point when within a change request. Updating its value will update the value across any expression blocks referencing it. The changed variable will go live to any published site once the change request is merged.
diff --git a/creating-content/version-control.md b/creating-content/version-control.md
new file mode 100644
index 00000000..f7fe7b12
--- /dev/null
+++ b/creating-content/version-control.md
@@ -0,0 +1,56 @@
+---
+icon: rectangle-vertical-history
+description: Keep track of changes, roll back to a previous version and more
+---
+
+# Version control
+
+You can easily monitor all the changes people have made to your content using to the **Version history** side panel.
+
+### Version history
+
+In the Version history of a space, you can see a list of all the actions that changed the content within it. These include:
+
+* When someone made [live edits](../collaboration/live-edits.md) to the space.
+* When someone merged a [change request](../collaboration/change-requests.md).
+* When someone performed a [Git Sync](../getting-started/git-sync/) operation.
+
+### View historical versions of content
+
+To view past versions of your content and see the changes that were made, click the **Version history** button in the [space header](../resources/gitbook-ui.md#space-header), or open the **Actions menu** next to the space or change request title and choose **Version history**.
+
+Click on any item in the list to see how your content looked at the point this change was made. This is very similar to how you view [change requests](../collaboration/change-requests.md).
+
+### Show changes
+
+When you are viewing an old version of your content, you can choose to highlight the differences between the old and current content — similar to [diff view in a change request](../collaboration/change-requests.md#diff-mode).
+
+To enable or disable this, use the **Show changes** toggle at the bottom of the **Version history** side panel.
+
+With show changes enabled, content that has changed will be highlighted by an icon on the left of its content block.
+
+### Viewing historical published versions
+
+If you're investigating the version history of a published space, you can also view previews of what the previous versions looked like in the published context (i.e. what the end user would see).
+
+You can do this by:
+
+{% stepper %}
+{% step %}
+From the version history side panel, select the revision
+{% endstep %}
+
+{% step %}
+Copy the ID at the end of the URL
+{% endstep %}
+
+{% step %}
+Add it at the end of your published docs URL as `/~/revisions/`
+{% endstep %}
+{% endstepper %}
+
+### Roll back to a previous version
+
+Rolling back allows you to revert a space’s content to the way it was at a previous point in time. This is helpful if you’ve accidentally made a breaking change or deleted content and need to quickly get back to a previous version of the space.
+
+To roll back to a previous version of your space, hover over the version in the side panel, click the **Actions button** and select **Rollback**.
diff --git a/creating-content/write-and-edit-with-ai.md b/creating-content/write-and-edit-with-ai.md
new file mode 100644
index 00000000..94324f30
--- /dev/null
+++ b/creating-content/write-and-edit-with-ai.md
@@ -0,0 +1,62 @@
+---
+description: Use GitBook AI to generate and build content for your page
+icon: wand-magic-sparkles
+---
+
+# Writing with GitBook AI
+
+{% include "../.gitbook/includes/pro-and-enterprise-hint.md" %}
+
+You can use GitBook AI to create content on any empty line on your page. It can create all kinds of content — formatted in Markdown — including code samples, templates, page summaries and more.
+
+
Write with GitBook AI.
+
+### Write with GitBook AI
+
+Press `Space` on any empty line, or type `/` and choose **Write with AI** to enter GitBook AI’s writing mode.
+
+You can instantly start typing any prompt you want. GitBook AI will analyze the prompt and generate content based on it. For example:
+
+> Write me a two-paragraph overview of why documentation is important for product teams.
+
+Alternatively, you can also choose from one of the suggested prompts or prompt starters:
+
+#### Continue writing
+
+If you click this option, GitBook AI will analyze the content on your current page and then generate more content based on that.
+
+#### Explain…
+
+Click this and then tell GitBook AI what you want it to explain. This isn’t limited by content on your page, so you can ask it to explain anything at all.
+
+#### Summarize
+
+As you can imagine, this option will summarize all the content on your page — great for writing a TL;DR at the bottom of a detailed document, or adding a quick summary at the top for people just checking in.
+
+#### Explain this
+
+This will break down the complex information on your page and explain it in simpler language — including explaining acronyms and other jargon. This is perfect if the page you’re reading involves a lot of complex information, or you want to add an explainer for less technical folks.
+
+#### Translate
+
+This mode will translate your current page into one of a set number of languages. If you want to translate into a language that’s not on the list, simply type it into the prompt box.
+
+### FAQs
+
+
+
+How does GitBook AI use my data?
+
+We always follow [our data protection practices](https://gitbook.com/docs/policies/privacy-and-security/statement) to keep your data private.
+
+GitBook AI does not use your data to train AI models. We will only share the information you add to GitBook AI with OpenAI for the sole purpose of providing you with GitBook AI’s features. Take a look at [OpenAI’s privacy policy](https://openai.com/enterprise-privacy) for more information.
+
+
+
+
+
+How much does GitBook AI cost?
+
+GitBook AI is available as part of GitBook’s Pro and Enterprise plans. If you have a Free or Plus plan, you’ll need to upgrade to use GitBook AI writing and editing. [Visit our pricing page](https://www.gitbook.com/pricing) to find out more about upgrading to Pro.
+
+
diff --git a/getting-started/git-sync/README.md b/getting-started/git-sync/README.md
new file mode 100644
index 00000000..2ee1455f
--- /dev/null
+++ b/getting-started/git-sync/README.md
@@ -0,0 +1,20 @@
+---
+icon: code-pull-request
+description: >-
+ Synchronize your GitBook content with GitHub or GitLab with GitBook’s
+ bi-directional integration
+---
+
+# GitHub & GitLab Sync
+
+
Set up Git Sync for your GitBook space.
+
+### Overview
+
+Git Sync allows technical teams to synchronize GitHub or GitLab repositories with GitBook and turn Markdown files into beautiful, user-friendly docs. Edit directly in GitBook’s powerful editor while keeping content synchronized with your codebase on GitHub or GitLab.
+
+Git Sync is bi-directional, so changes you make directly in GitBook’s editor are automatically synced, as are any commits made on GitHub or GitLab. This allows developers to commit directly from GitHub or GitLab and technical writers, instructional designers and product managers to edit, discuss and feedback changes directly in GitBook.
+
+{% hint style="info" %}
+Only [administrators and creators](../../account-management/member-management/roles.md) can enable and configure Git Sync.
+{% endhint %}
diff --git a/getting-started/git-sync/commits.md b/getting-started/git-sync/commits.md
new file mode 100644
index 00000000..7e519608
--- /dev/null
+++ b/getting-started/git-sync/commits.md
@@ -0,0 +1,32 @@
+# Commit messages & Autolink
+
+By default, when exporting content from GitBook to the Git repository, GitBook will generate a commit message based on the merged change request:
+
+```
+GITBOOK-14: Improve documentation about users management
+```
+
+## Autolink `GITBOOK-` in GitHub and GitLab
+
+If you want to automatically resolve your GitBook change request IDs (e.g. _GITBOOK-123_) in commits to links, you can enable this using GitHub’s _Autolink references_ feature. See instructions on [GitHub](https://help.github.com/en/github/administering-a-repository/configuring-autolinks-to-reference-external-resources).
+
+Use the following URL format, where `spaceId` corresponds to your space’s URL:
+
+`/`
+
+
Autolink setup.
+
+## Customize the commit message template
+
+When using GitBook with a [monorepo](monorepos.md), or when you have specific guidelines for commit messages; you might want to customize the message used by GitBook when pushing a commit to Git.
+
+The template can contain the following placeholders:
+
+* `{change_request_number}` unique numeric ID for the change request
+* `{change_request_subject}` the subject of the change request when merged, or `No subject` if none has been provided.
+
+The default template is:
+
+```
+GITBOOK-{change_request_number}: {change_request_subject}
+```
diff --git a/getting-started/git-sync/content-configuration.md b/getting-started/git-sync/content-configuration.md
new file mode 100644
index 00000000..6759618c
--- /dev/null
+++ b/getting-started/git-sync/content-configuration.md
@@ -0,0 +1,113 @@
+---
+description: Configure Git Sync with extra functionalities
+---
+
+# Content configuration
+
+If you’d like to configure Git Sync further, you can add a `.gitbook.yaml` file at the root of your repository to tell GitBook how to parse your Git repository.
+
+{% code title=".gitbook.yaml" %}
+```yaml
+root: ./
+
+structure:
+ readme: README.md
+ summary: SUMMARY.md
+
+redirects:
+ previous/page: new-folder/page.md
+```
+{% endcode %}
+
+### Root
+
+The path to lookup for your documentation defaults to the root directory of the repository. Here’s how you can tell GitBook to look into a `./docs` folder:
+
+{% code title=".gitbook.yaml" %}
+```yaml
+root: ./docs/
+```
+{% endcode %}
+
+{% hint style="warning" %}
+**All other options that specify paths will be relative to this root folder**. So if you define root as `./docs/` and then `structure.summary` as `./product/SUMMARY.md`, GitBook will actually look for a file in `./docs/product/SUMMARY.md`.
+{% endhint %}
+
+### Structure
+
+The structure accepts two properties:
+
+* **`readme`**: Your documentation’s first page. Its default value is `./README.md`
+* **`summary`**: Your documentation’s table of contents. Its default value is `./SUMMARY.md`
+
+The value of those properties is a path to the corresponding files. The path is relative to the “root” option. For example, here’s how you can tell GitBook to look into a `./product` folder for the first page and summary:
+
+{% code title=".gitbook.yaml" %}
+```yaml
+structure:
+ readme: ./product/README.md
+ summary: ./product/SUMMARY.md
+```
+{% endcode %}
+
+{% hint style="warning" %}
+When Git Sync is enabled, **remember not to create or modify readme files** through GitBook's UI. The readme file should be managed exclusively in your GitHub/GitLab repository to avoid conflicts and duplication issues.
+{% endhint %}
+
+### Summary
+
+The `summary` file is a Markdown file (`.md`) that should have the following structure:
+
+{% code title="./SUMMARY.md" %}
+```markdown
+# Summary
+
+## Use headings to create page groups like this one
+
+* [First page’s title](page1/README.md)
+ * [Some child page](page1/page1-1.md)
+ * [Some other child page](part1/page1-2.md)
+
+* [Second page’s title](page2/README.md)
+ * [Some child page](page2/page2-1.md)
+ * [Some other child page](part2/page2-2.md)
+
+## A second-page group
+
+* [Another page](another-page.md)
+```
+{% endcode %}
+
+Providing a custom summary file is optional. By default, GitBook will look for a file named `SUMMARY.md` in your `root` folder if specified in your config file, or at the root of the repository otherwise.
+
+If you don’t specify a summary, and GitBook does not find a `SUMMARY.md` file at the root of your docs, GitBook will infer the table of contents from the folder structure and the Markdown files below.
+
+{% hint style="info" %}
+The summary markdown file is **a mirror of the** **table of contents** of your GitBook space. So even when no summary file is provided during an initial import, GitBook will create one and/or update it whenever you update your content using the GitBook editor.
+
+Because of this, it’s not possible to reference the same Markdown file twice in your `SUMMARY.md` file, because this would imply that a single page lives at two different URLs in your GitBook space.
+{% endhint %}
+
+### Redirects
+
+Redirects allow you to define redirects in your `.gitbook.yaml` configuration file. The path is relative to the “root” option. For example, here’s how you can tell GitBook to redirect users accessing a past url `/help` to a new url `/support`
+
+{% code title=".gitbook.yaml" %}
+```yaml
+root: ./
+
+redirects:
+ help: support.md
+```
+{% endcode %}
+
+{% hint style="info" %}
+Redirects you define in a space’s configuration file are scoped to the corresponding space. We recommend creating [site redirects](../../publishing-documentation/site-redirects.md) for most cases as they apply to the whole site, across spaces.
+{% endhint %}
+
+{% hint style="warning" %}
+With Git, when a file is moved many times, the file is removed and a new one is created. This makes it impossible for GitBook to know that a folder has been renamed, for example. Make sure to double-check and add redirects where needed.
+{% endhint %}
+
+
+
diff --git a/getting-started/git-sync/enabling-github-sync.md b/getting-started/git-sync/enabling-github-sync.md
new file mode 100644
index 00000000..951fd08c
--- /dev/null
+++ b/getting-started/git-sync/enabling-github-sync.md
@@ -0,0 +1,60 @@
+---
+description: Set up and authorize the GitHub integration for GitBook
+---
+
+# Enabling GitHub Sync
+
+### Getting started
+
+In the space you want to sync with your GitHub repo, head to the [space header](../../resources/gitbook-ui.md#space-header) in the top right, and select **Configure**. From the provider list, select **GitHub Sync**.
+
+
GitHub Sync configuration options.
+
+### Authenticate with GitHub
+
+If you’re setting up GitHub Sync for the first time and haven’t already linked a GitHub account, you’ll be prompted to do that when you begin configuring Git Sync. If you’ve already linked your account, you may still need to authenticate via GitHub.
+
+{% hint style="warning" %}
+If you see a **'Potential duplicated accounts'** error message at this step, this means your GitHub account is already linked with another GitBook user account.
+
+To help you identify which accounts are linked, you will have to log out from this session and log in using the sign-in with GitHub method.
+
+If you already know your GitBook account associated with GitHub you can log into that user account and unlink your GitHub account (done in settings) before logging back in and linking your current account.
+
+Read more on our [troubleshooting page](troubleshooting.md#potential-duplicated-accounts-when-signing-in).
+{% endhint %}
+
+### Install the GitBook app to your GitHub account
+
+If you haven’t already done so, you’ll see a prompt to add the [GitBook app](https://github.com/apps/gitbook-com) to your GitHub account.
+
+Follow the instructions in the GitHub popover and either give GitBook specific repository permissions, or allow access to all repositories, depending on your needs.
+
+### Select a repository and branch
+
+Select the account and repository you want to keep in sync with your GitBook content.
+
+{% hint style="info" %}
+**Can’t see your repository?** If you can't find your repository in the list, make sure that you've installed the [GitBook GitHub app](https://github.com/apps/gitbook-com) in the right scope (i.e. your personal account or the GitHub org where the repository lives). You should also check that you’ve configured the correct repository access in the GitBook GitHub app.
+{% endhint %}
+
+Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.
+
+### Perform an initial sync
+
+When syncing for the first time, you’ll have the option to sync in one of two directions:
+
+1. Git**Book** -> Git**Hub** will sync your space’s content **to** the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.
+2. Git**Hub** -> Git**Book** will sync your space’s content **from** the selected branch. This is great if you have existing Markdown content in a repository and want to bring it into GitBook.
+
+### Write and commit
+
+You’re good to go. You’ll notice that if your space was in [live edit](../../collaboration/live-edits.md) mode, live edits are now locked. This allows us to reliably sync content to your repository when someone in your team merges a[ change request](../../collaboration/change-requests.md) in GitBook.
+
+When you edit on GitBook, every change request merge will result in a commit to your selected GitHub branch.
+
+When you commit to GitHub, every commit will be synced to your GitBook space as a history commit.
+
+{% hint style="warning" %}
+The GitHub app that powers our GitHub integration is currently not available to customers on GitHub Enterprise Server instances.
+{% endhint %}
diff --git a/getting-started/git-sync/enabling-gitlab-sync.md b/getting-started/git-sync/enabling-gitlab-sync.md
new file mode 100644
index 00000000..fe603f5d
--- /dev/null
+++ b/getting-started/git-sync/enabling-gitlab-sync.md
@@ -0,0 +1,58 @@
+---
+description: Set up and authorize the GitLab integration for GitBook
+---
+
+# Enabling GitLab Sync
+
+### Getting started
+
+In the space you want to sync with your GitLab repo, head to the space menu in the top right, and select **Synchronize with Git**. From the provider list, select **GitLab Sync**, and click **Configure**.
+
+
GitLab Sync configuration options.
+
+### Generate and enter your API access token
+
+You can generate an API access token in your GitLab user settings.
+
+{% hint style="info" %}
+There are two types of access tokens in GitLab: Project and Personal. Note that in order for the integration to work you’ll need to use a Personal token, which you can generate from your GitLab user preferences menu.
+{% endhint %}
+
+Ensure that you enable the following access for your token:
+
+* `api`
+* `read_repository`
+* `write_repository`
+
+If the tokens you create also have a specific role attached to them, also make sure that it has a `Maintainer` or `Admin` role.
+
+Then you can paste the token into the API access token field when configuring your GitLab integration.
+
+### Select a repository and branch
+
+Select the repository you want to keep in sync with your GitBook content.
+
+{% hint style="info" %}
+**Can’t see your repository?** Ensure you’ve set the correct permissions when creating your API token.
+{% endhint %}
+
+Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.
+
+{% hint style="warning" %}
+For many GitLab repositories, the `main` branch might be automatically set to protected. If this is the case, we recommend adding a specific branch to sync your content between. You can then merge this into `main` and keep the protection in place.
+{% endhint %}
+
+### Perform an initial sync
+
+When syncing for the first time, you’ll have the option to sync in one of two directions:
+
+1. Git**Book** -> Git**Lab** will sync your space’s content **to** the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.
+2. Git**Lab** -> Git**Book** will sync your space’s content **from** the selected branch. This is great if you have existing markdown content in a repository and want to bring it into GitBook.
+
+### Write and commit
+
+You’re good to go. You’ll notice that if your space was in [live edit](../../collaboration/live-edits.md) mode, live edits are now locked. This allows GitBook to reliably sync content to your repository when someone in your team merges a[ change request](../../collaboration/change-requests.md) in GitBook.
+
+When you edit on GitBook, every change request merge will result in a commit to your selected GitLab branch.
+
+When you commit to GitLab, every commit will be synced to your GitBook space as a history commit.
diff --git a/getting-started/git-sync/github-pull-request-preview.md b/getting-started/git-sync/github-pull-request-preview.md
new file mode 100644
index 00000000..9607ab7e
--- /dev/null
+++ b/getting-started/git-sync/github-pull-request-preview.md
@@ -0,0 +1,27 @@
+---
+description: See a preview of your content when making a pull request in GitHub
+---
+
+# GitHub pull request preview
+
+When you submit a pull request (PR) to a GitHub branch that has been synced to a GitBook space, you can preview the content before merging. This allows you to check the impact of changes before merging them.
+
+You can use this feature to have a final layer of checks before merging a PR, allowing you to see your changes in a non-production environment before merging it into your synced branch.
+
+
+
+### Be sure to only create readme files in your repo
+
+When Git Sync is enabled, be careful not to create readme files through the GitBook UI. Creating readme files through the GitBook UI:
+
+* Creates duplicate README files in your repository
+* Causes rendering conflicts between GitBook and GitHub
+* May break builds and deployment processes
+* Results in unpredictable file precedence
+
+This includes files named README.md, readme.md, Readme.md, and README (without extension). Instead, remember to manage your README file directly in your git repository.
+
+### Still facing errors?
+
+Make sure that:
+
+* Your repository **has a** `README.md` **file** at its root (or at the `root` folder specified in your `.gitbook.yaml`) that was created directly in your git repository. This file is required and is used as the homepage for your documentation. For more details, refer to our [content configuration](content-configuration.md).
+* If you have YAML frontmatters in your Markdown files, make sure they are valid using a [linter](http://www.yamllint.com).
+
+## GitBook is not using my `docs` folder
+
+By default, GitBook uses the root of the repository as a starting point. A specific directory can be specified to scope the markdown files. Take a look at our documentation on [content configuration](content-configuration.md) for more details.
+
+## GitBook is creating new markdown files
+
+**When synchronizing and editing from GitBook** with an existing Git repository, GitBook may create new markdown files instead of using the existing ones. This is done to ensure GitBook doesn't overrite files that existed in your repository before.
+
+## Redirects aren't working correctly
+
+The YAML file needs to be correctly formatted for the redirects to work. Errors such as incorrect indentation or whitespace can result in your redirects not working. [Validating your YAML file](https://www.yamllint.com/) can ensure that the redirects will work smoothly.
+
+When setting redirects, do not add any leading slashes. For example, trying to redirect to `./misc/support.md` will not work.
+
+It's also important to consider that as long as a page exists for a path, GitBook won’t be looking for a possible redirect. So if you're setting up a redirect for an old page to a new one, you will need to remove the old page in order for the redirect to work.
+
+## My repository is not listed
+
+### For GitHub repositories
+
+Make sure that you have installed the GitBook GitHub app to the correct locations (when installing the app, you can choose to install it to your personal GitHub, or to any organization you have permissions for) and that you have given the app the correct repository permissions.
+
+### For GitLab repositories
+
+Make sure that your access token has been configured with the following access:
+
+* `api`
+* `read_repository`
+* `write_repository`
+
+## Nothing happens on GitBook after adding a new file to my repository
+
+{% hint style="warning" %}
+**This section specifically addresses problems when a `SUMMARY.md` file already exists**
+
+If your repository does not include a `SUMMARY.md` file, GitBook will automatically create one upon the first sync. This means that if you edited your content from GitBook at least once after setting up Git sync, GitBook should have created this file automatically.
+{% endhint %}
+
+If after updating your repository by adding or modifying a markdown file, you do not see the update reflected on GitBook and the sidebar doesn’t indicate an error during the sync, your modified file(s) is probably not listed in [your `SUMMARY.md` file](content-configuration.md#summary).
+
+This could either be because you created the file manually, or because you made an edit on GitBook and the GitBook to Git export phase of the sync created it for you.
+
+The content of this file mirrors your [table of contents](../../resources/gitbook-ui.md#table-of-contents) on GitBook and is used during the Git to GitBook import phase of the sync to recreate your table of contents and re-conciliate upcoming updates from the repository with your existing content on GitBook.
+
+If after ensuring that all your files are included in the `SUMMARY.md` file there’s still nothing happening on GitBook, don’t hesitate to [contact support](https://gitbook.com/docs/help-center/further-help/how-do-i-contact-support) for assistance.
+
+## GitHub preview is not showing
+
+If your GitHub preview is not showing, it might be because your GitSync integration was configured before January 2022. Versions of GitSync configured before this date do not include GitHub Preview.
+
+You should have received a notification requesting you to accept an updated permission request to enable read-only access to PRs.
+
+In case you did not receive the notification, to troubleshoot you need to update to the new version:
+
+1. Uninstall the GitSync integration from your organization.
+2. Reinstall the new version with the updated permissions.
+
+Please note that uninstalling the GitSync integration will require reconfiguring the integration again on any spaces it was previously connected to.
+
+## Potential duplicated accounts when signing in
+
+This error usually occurs when the GitHub account that you use to set up the sync is already associated with a different GitBook user account.
+
+A good way to identify which GitBook account the GitHub account is already linked to is:
+
+1. Log out from your current GitBook user session (i.e. `name@email.com`)
+2. Log out from any GitHub user sessions.
+3. Go to [the Log in page](https://app.gitbook.com/login).
+4. Select the "Sign in with GitHub" option.
+5. Enter your GitHub credentials.
+6. Once logged in, go to [the account settings](https://app.gitbook.com/account) and either:
+ 1. Unlink the account from the "Third-party Login > GitHub" section in the Personal setting
+ 2. Delete the account altogether if you do not need it.
+7. Log out from the session.
+8. Log back in using your `name@email.com` GitBook account.
+9. Try to set up Git Sync again.
diff --git a/getting-started/import.md b/getting-started/import.md
new file mode 100644
index 00000000..82db67d0
--- /dev/null
+++ b/getting-started/import.md
@@ -0,0 +1,98 @@
+---
+description: >-
+ How to import existing content into GitBook from Confluence, Notion, Git and
+ more
+icon: arrow-up-to-line
+---
+
+# Importing content
+
+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.md#import-using-git-sync).
+
+## Using the Import Panel
+
+### Supported import formats
+
+GitBook supports imports from websites or files in the following formats:
+
+* Markdown (`.md` or `.markdown`)
+* HTML (`.html`)
+* Microsoft Word (`.docx`)
+
+We 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.
+
+{% 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 space, you’ll have the option to import content from the bottom sheet of the first empty page.
+
+Alternatively, you can always import a page or subpage by selecting **New page** > **Import new pages** in the [table of contents](../resources/gitbook-ui.md#table-of-contents), or 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**.
+
+***
+
+## Import using Git Sync
+
+For importing large volumes of content into GitBook, we recommend using [Git Sync](git-sync/). Unlike our integrated import tool, 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 to [importing content into GitBook using Git Sync](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/import-or-migrate-your-content-to-gitbook-with-git-sync).
+{% endhint %}
+
+Here’s how to do it:
+
+{% 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 space 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 spaces and Git Sync
+
+To organize your content, create one or more spaces 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 spaces. You’ll need to synchronize your space 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 %}
diff --git a/getting-started/quickstart.md b/getting-started/quickstart.md
new file mode 100644
index 00000000..58ac45b5
--- /dev/null
+++ b/getting-started/quickstart.md
@@ -0,0 +1,52 @@
+---
+description: Get up and running in GitBook and publish your first docs site in minutes
+icon: bolt
+---
+
+# Quickstart
+
+### Getting started
+
+You’ll need a GitBook account to start publishing documentation.
+
+Sign up
+
+### Create a docs site
+
+When you first sign up, you’ll have a chance to create a docs site from the docs site wizard. You can launch the wizard again to create a new site at any point by clicking the **+** button next to the **Docs sites** header in the sidebar.
+
+
Publish your first site in just a few minutes using the docs site wizard.
+
+The docs site wizard will take you through the flow of creating your first site. You’ll need to give your site a name, choose if you want to start from scratch with an empty site or add our sample content, and whether or not you want to publish your docs right away.
+
+### Edit your content
+
+Now that you’ve created a site, you can edit or import your content. If you have an existing repository on GitHub or GitLab with your documentation, you can easily migrate and sync your content to GitBook using [Git Sync](git-sync/). Find out more in [our guide to migrating content using Git Sync](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/import-or-migrate-your-content-to-gitbook-with-git-sync).
+
+After importing your content, you can edit your pages using GitBook’s built-in editor and do things like [add interactive blocks](../creating-content/blocks/), customize the [layout of your pages](../creating-content/content-structure/page.md) and more.
+
+Check out these resources if you’d like to learn more about the editing experience in GitBook:
+
+
+
+### Customize your site
+
+Not only can you edit the content of your site, you can also customize many settings related to the look and feel of your site when it’s published.
+
+You can change things like the [logo, colors & fonts](../publishing-documentation/customization/), add more structure through [site sections](../publishing-documentation/site-structure/site-sections.md) and [variants](../publishing-documentation/site-structure/variants.md), or update your [site’s visibility](../publishing-documentation/site-settings.md#audience) settings.
+
+You can read more about customizing your docs in the resources below:
+
+
+
+### Publish your documentation
+
+Finally, you’re ready to publish your site into the world. If you haven’t already published your site from the wizard, you can publish your site from your site’s dashboard at any time.
+
+After publishing your site, you’ll get a link that you’re able to share with anyone!
+
+If you’re running into problems or have any questions, we’re here to help. [Join our community](https://github.com/orgs/GitbookIO/discussions) or [send our support team a message](https://gitbook.com/docs/help-center/further-help/how-do-i-contact-support) and we’ll help you from there.
+
+{% hint style="success" %}
+Want to explore publishing in more details? Check out [our complete guide to creating and publishing content in GitBook](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/complete-guide-to-publishing-docs-gitbook).
+{% endhint %}
diff --git a/help-and-faq/contributing.md b/help-and-faq/contributing.md
deleted file mode 100644
index 9d3da3e2..00000000
--- a/help-and-faq/contributing.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-icon: layer-plus
----
-
-# Contributing
-
-Thank you for investing your time in contributing to our documentation! Any contribution you make will be reviewed by our team.
-
-The official developer docs for GitBook are hosted on [https://docs.gitbook.com/](https://docs.gitbook.com/). Our documentation uses one of GitBook's most useful features—[Git Sync](https://docs.gitbook.com/product-tour/git-sync)!
-
-Git Sync allows you to keep your GitBook site up to date with a remote repository either on GitHub or GitLab. In our case we have the our repository `public-docs` synced with [https://docs.gitbook.com/](https://docs.gitbook.com/).
-
-This means that any changes reviewed, approved, and merged into this directory will automatically be deployed!
-
-Head to our repository below to get started.
-
-{% embed url="https://github.com/GitbookIO/public-docs" %}
diff --git a/help-and-faq/faq/README.md b/help-and-faq/faq/README.md
deleted file mode 100644
index fe888dcb..00000000
--- a/help-and-faq/faq/README.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-icon: message-question
----
-
-# FAQ
-
diff --git a/help-and-faq/faq/content-creation-faq.md b/help-and-faq/faq/content-creation-faq.md
deleted file mode 100644
index 96f4f6fc..00000000
--- a/help-and-faq/faq/content-creation-faq.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Content creation FAQ
-
-## What browsers are supported by GitBook?
-
-GitBook supports the current versions of [Chrome](https://www.google.com/chrome/), [Firefox](http://www.mozilla.org/firefox/), [Safari](http://www.apple.com/safari/), and [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge).
-
-## Does GitBook support RTL languages?
-
-We have RTL support in mind, but it’s not yet ready. For now, only paragraphs and headings will automatically detect RTL text and adapt its layout. Lists and other content blocks are not aligned properly. Also, you may have noticed a poor font quality being used for your language.
-
-## Is there a limit on the documentation import size?
-
-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.**
-
-## **How can I export my content?**
-
-We recommend exporting your content in Markdown format by enabling [GitHub or GitLab sync](../../integrations/git-sync/). You can also export your content via PDF but you may hit some limits in case of larger spaces.
-
-## Can I move a page from one space to another?
-
-We do not support moving single pages between spaces at this time. We recommend you copy and paste the content as needed. In cases of larger content reorganization where you will need to move a number of pages between spaces, we recommend you contact our support team who can guide you through moving your content via GitHub or GitLab sync.
-
-{% hint style="info" %}
-To easily select multiple blocks you can use block selection mode, which is enabled by hitting the esc key. To copy an entire page of text, you can hit esc to enable block selection and then hit cmd + a to select all content on a page and then copy and paste to a new space.
-{% endhint %}
-
-## Can I move a space between organizations?
-
-Yes, you can! [Read more about how to move a space.](../../content-editor/editor/content-structure/what-is-a-space.md#move-a-space)
-
-## Can I export my content in Markdown format?
-
-We don't have the ability to export pages as Markdown in the GitBook app, but you can sync a space to GitHub or GitLab and generate a markdown export that way. Note that there might be a few exceptions where customized blocks appear as HTML.
-
-## How do I revert to the previous version of my content?
-
-Admins and creators can click the **rollback** button while viewing a specific history item to[ roll the space back ](../../content-editor/activity-history.md#rolling-back-to-a-previous-version)to this point in time.
-
-## Do you support offline contributions?
-
-Not at the moment!
-
-## Do you have a mobile or a desktop app?
-
-No, sorry.
diff --git a/help-and-faq/faq/faqs-1.md b/help-and-faq/faq/faqs-1.md
deleted file mode 100644
index bc2622a9..00000000
--- a/help-and-faq/faq/faqs-1.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-hidden: true
-noRobotsIndex: true
----
-
-# FAQs
-
-### Does GitBook have a find and replace feature?
-
-While there isn't a way to globally find and replace all instances of a term across your GitBook content, if you use our git sync feature, you can more easily find all instances of a word and replace it. Once you merge these updates in GitHub or GitLab, the changes will be synced and reflected in your content.
diff --git a/help-and-faq/faq/faqs.md b/help-and-faq/faq/faqs.md
deleted file mode 100644
index f7c5f200..00000000
--- a/help-and-faq/faq/faqs.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-description: Find out more about how GitBook handles your data and security.
----
-
-# Security FAQs
-
-## Where and how is my data stored?
-
-All user data and content is stored in the US on [Google Cloud](https://cloud.google.com), which is backed by the same infrastructure and security that Google uses for its own services.
-
-Customer data is stored in U.S. data centers. Some data (HTML pages & assets) may be cached in other geographies by our CDN. Access to private content through our CDN is always validated through our application servers using a complex permissions system.
-
-Google follows or even leads most of the industry’s best practices and is compliant with most major security [standards and certifications](https://cloud.google.com/security/compliance/).
-
-## **Is GitBook SOC 2 certified?**
-
-Yes. Customers and prospects can request access to the audit report [here.](https://app.vanta.com/gitbook.com/trust/riuibmbkcopvbwgqxul01a)
-
-## Security as a company value
-
-To find more information about how GitBook handles security head over to our Security FAQ.
-
-{% embed url="https://policies.gitbook.com/privacy-and-security/security/security-faq" %}
diff --git a/help-and-faq/faq/how-do-i-solve-connectivity-issues.md b/help-and-faq/faq/how-do-i-solve-connectivity-issues.md
deleted file mode 100644
index a115c298..00000000
--- a/help-and-faq/faq/how-do-i-solve-connectivity-issues.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-description: Avoiding network related access issues.
----
-
-# How do I solve connectivity issues?
-
-Here is a list of services GitBook relies on to run its app. If you have any kind of firewall or application that blocks all traffic or some of the sites listed below, you should add an exception to allow GitBook to work in your network.
-
-### App
-
-* `*.gitbook.com`
- * `app.gitbook.com`
- * `api.gitbook.com`
- * `content.gitbook.com`
- * `clearbit-risk.gitbook.com`
- * `files.gitbook.com`
- * `segment-cdn.gitbook.com`
- * `segment-api.gitbook.com`
-* `*.gitbook.io`
-
-### CDNs
-
-* `cdn.iframe.ly`
-* `cdn.polyfill.io`
-
-### Google APIs
-
-* `*.googleapis.com`
- * `firebase.googleapis.com`
- * `firestore.googleapis.com`
- * `www.googleapis.com`
-* `*.googleusercontent.com`
-* `*.googletagmanager.com`
-
-### Sentry
-
-* `*.sentry.io`
-
-### Troubleshooting
-
-Here are a few possible causes for your connectivity issues:
-
-* Temporary local or regional network issues
-* Browser security settings
-* Browser plugins
-* Security/antivirus
-* Firewalls
-* Plugins/extensions
-* Proxies
-* Local network settings
-* Your provider
-* Your area/region
-
-{% hint style="info" %}
-Please always check [our status page](https://www.gitbookstatus.com/) to see if there are any outages to our app or the third-party services we rely on.
-{% endhint %}
-
-If everything fails, please share the details with [GitBook Support](mailto:support@gitbook.com).
diff --git a/help-and-faq/faq/report-bugs.md b/help-and-faq/faq/report-bugs.md
deleted file mode 100644
index 7a78860d..00000000
--- a/help-and-faq/faq/report-bugs.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-description: >-
- Encountered a bug? Find out how to provide all the essential information for
- speedy resolution.
----
-
-# How do I report bugs?
-
-Bugs should be reported using the messaging widget available from your dashboard or by sending an email to [support@gitbook.com](mailto:support@gitbook.com). In order to get the best help possible, please provide as much context on how you encountered the bug.
-
-## **Generate Network Captures for Troubleshooting**
-
-**HAR**
-
-A HAR capture (HTTP Archives) records the requests and responses that your browser makes with the GitBook Application.
-
-### **Chrome**
-
-1. In Chrome, go to the page within GitBook where you are experiencing trouble.
-2. At the top-right of your browser window, click the Chrome menu (⋮).
-3. Select **tools > developer tools**. The developer tools window opens as a docked panel at the side or bottom of Chrome.
-4. Click the **network** tab.
-5. Select **preserve log**.
-6. You will see a red circle at the top left of the Network tab. This means the capture has started. If the circle is black, click the **black circle** to start recording activity in your browser.
-7. **Refresh the page** and reproduce the problem while the capture is running.
-8. After you successfully reproduce the issue, right click on any row of the activity pane and select **Save as HAR with content**.
-9. Select the **console** tab
-10. Right-click anywhere in the console and select **save as...**.
-11. Name the log file **Chrome-console.log**.
-12. Send both files as shared links in a reply to your case.
-
-### **Firefox**
-
-1. In Firefox, go to the page within GitBook where you are experiencing trouble.
-2. Click the Firefox menu (Three horizontal parallel lines) at the top-right of your browser window.
-3. Select **web developer > network**.
-4. The developer tools window opens as a docked panel at the side or bottom of Firefox.
-5. Click the **network** tab.
-6. Select **persist logs**.
-7. **Refresh the page** and reproduce the problem while the capture is running.
-8. After you successfully reproduce the issue, right-click any row of the activity pane and select **Save all as HAR**.
-9. Select the **console** tab.
-10. Right-click any row and select **select all**.
-11. Paste the content in a text file and name it **console-log.txt**.
-12. Send both files as shared links in a reply to your case.
-
-### **Safari**
-
-1. In Safari, go to the page within GitBook where you are experiencing trouble.
-2. In the menu bar at the top, click **develop** and select **show web inspector**.
-3. Click the **console** tab and select **preserve log**.
-4. Go back to the **network** tab.
-5. **Refresh the page** and reproduce the problem while the capture is running.
-6. After you successfully reproduce the issue, right-click any row of the activity pane and select **export HAR**.
-7. Click the **console** tab.
-8. Right-click any row and select **select all**.
-9. Paste the content in a text file and name it **console-log.txt**.
-10. Send both files as shared links in a reply to your case.
-
-### **Internet Explorer (IE11)**
-
-1. In Internet Explorer, go to the page within GitBook where you are experiencing trouble.
-2. Click the gear icon in the top right.
-3. Select **F12 developer** tools.
-4. Click the **network** tab.
-5. Clear the **clear entries on navigate** option, which is selected by default. The icon looks like blue arrow with a red X.
-6. The green play button (**start profiling session**), should be selected by default. This means the capture function is running.
-7. Refresh the the page and reproduce the problem while the capture is running.
-8. Once you have reproduced the issue, click the **export as HAR** icon. The icon looks like a floppy disk.
-9. Click the **console** tab.
-10. Right-click any row and select **copy all.**
-11. Paste the content in a text file and name it **console-log.txt**.
-12. Send both files as shared links in a reply to your case.
-
-### **Edge**
-
-1. In Edge, go to the page within GitBook where you are experiencing trouble.
-2. At the top-right of your browser window, click the Edge menu (⋮)
-3. Select **developer tools**.
-4. Click the **network** tab.
-5. Clear the **clear entries on navigate** option, which is selected by default. The icon looks like blue arrow with a red X.
-6. The green play button (**start profiling session**), should be selected by default. This means the capture function is running.
-7. Refresh the the page and reproduce the problem while the capture is running.
-8. Once you have reproduced the issue, click the **export as HAR** icon. The icon looks like a floppy disk.
-9. Click the **console** tab.
-10. Right-click any row and select **copy all.**
-11. Paste the content in a text file and name it **console-log.txt**.
-12. Send both files as shared links in a reply to your case.
diff --git a/help-and-faq/faq/support.md b/help-and-faq/faq/support.md
deleted file mode 100644
index d550172d..00000000
--- a/help-and-faq/faq/support.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-description: >-
- Our friendly support team is here to help. Learn what information to share and
- when can you expect a response.
----
-
-# How do I contact support?
-
-There are two ways to get in touch with us:
-
-- You can submit a support request via the GitBook app. When you’re logged in, click on the **settings icon** in the [sidebar](https://docs.gitbook.com/getting-started/overview#sidebar). Click **Help & Feedback** and then click **Contact Support**.
-- You can email [support@gitbook.com](mailto:support@gitbook.com) directly.
-
-## What information should I share?
-
-To help _us_ help _you_ as efficiently as possible, please be sure to send us all relevant details:
-
-- If your support request relates to a specific space, please make sure to include a link to it.
-- Please describe the steps that you are taking, what happens when you take those steps, and what you expect to happen instead.
-- If you are running into an error message, please pass along the error message in full.
-- Can you send us a screenshot to show us what you’re seeing? Or, can you send us a short video to show us the steps that you are taking? These are extremely helpful.
-
-## When will I get a response?
-
-We aim to respond to every message within 1 business day. At busy times this might not be possible, but we’ll always get back to you as soon as we are able.
-
-Please note our support team works Monday to Friday, from 9 am to 5 pm GMT (+/- 3 hours).
-
-## Why has the support widget changed?
-
-We’ve made some internal changes to help us improve the support that we offer. As part of these changes, we have moved to a new help desk system. The main differences you’ll notice are:
-
-- We have a new workflow in the GitBook app to use when sending us a support request.
-- Our workflow will gather the key information we need to help us assist you faster.
-
-Please note that **we do not offer real-time support** via this widget, this isn’t something that we can currently provide. We aim to respond as soon as possible and when we do, your inbox will notify you!
diff --git a/help-and-faq/keyboard-shortcuts.md b/help-and-faq/keyboard-shortcuts.md
deleted file mode 100644
index 68679370..00000000
--- a/help-and-faq/keyboard-shortcuts.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-description: Helping you to make changes to your GitBook documentation even faster!
-icon: keyboard
----
-
-# Keyboard shortcuts
-
-Shortcut keys allow easy and quick methods for navigating or editing content.
-
-{% hint style="info" %}
-**Permissions**
-
-All member roles can use keyboard shortcuts.
-{% endhint %}
-
-## Navigation
-
-| Mac | Windows | Description |
-| ----- | -------- | ---------------------------------- |
-| `Esc` | `Esc` | Close a dialog or the search panel |
-| `⌘+K` | `Ctrl+K` | Open the quick find panel |
-
-## Editing
-
-| Mac | Windows | Description |
-| ----------- | -------------- | ------------------------------------------------------------------------------------------------ |
-| `⌘+C` | `Ctrl+C` | Copy |
-| `⌘+V` | `Ctrl+V` | Paste |
-| `⌘+Shift+V` | `Ctrl+Shift+V` | Paste as text, without formatting |
-| `⌘+Z` | `Ctrl+Z` | Undo |
-| `⌘+Shift+Z` | `Ctrl+Shift+Z` | Redo |
-| `⌘+Enter` | `Ctrl+Enter` | Exit from content block (code, tabs, table, quote ...) |
-| `/` | `/` | Open block-insert palette. |
-| `⌘+/` | `Ctrl+/` | Open block-modifier palette. |
-| `⌘+B` | `Ctrl+B` | Toggle bold |
-| `⌘+I` | `Ctrl+I` | Toggle italic |
-| `⌘+Shift+S` | `Ctrl+Shift+S` | Toggle strikethrough |
-| `⌘+E` | `Ctrl+E` | Toggle inline code |
-| `⌘+K` | `Ctrl+K` | Insert or toggle link |
-| `Tab` | `Tab` |
In a list, increase item indent level.
In a code block, increase indentation level.
|
-| `Shift+Tab` | `Shift+Tab` |
In a list, decrease item indent level.
In a code block, decrease indentation level.
|
-| `Esc` | `Esc` | Selects the entire block |
diff --git a/help/connectivity-issues.md b/help/connectivity-issues.md
index 7bbf691f..3ea98ba0 100644
--- a/help/connectivity-issues.md
+++ b/help/connectivity-issues.md
@@ -54,4 +54,4 @@ Here are a few possible causes for your connectivity issues:
Please always check [our status page](https://www.gitbookstatus.com/) to see if there are any outages to our app or the third-party services we rely on.
{% endhint %}
-If everything fails, please share the details with [GitBook Support](mailto:support@gitbook.com).
+If everything fails, please share the details with [GitBook Support](mailto:support@gitbook.com).
diff --git a/help/support.md b/help/support.md
index 75554a2a..ac5f8af0 100644
--- a/help/support.md
+++ b/help/support.md
@@ -8,7 +8,7 @@ description: >-
There are two ways to get in touch with us:
-- You can submit a support request via the GitBook app. When you’re logged in, click on the **cog** :gear: **icon** in the [sidebar](https://docs.gitbook.com/getting-started/overview#sidebar). Click **Help & Feedback** and then click **Contact Support**.
+- You can submit a support request via the GitBook app. When you’re logged in, click on the **question mark** :QUESTION-MARK: **icon** in the [sidebar](https://gitbook.com/docs/resources/gitbook-ui#sidebar). Click **Contact us** and then click **Send us a message**.
- You can email [support@gitbook.com](mailto:support@gitbook.com) directly.
## What information should I share?
diff --git a/integrations/git-sync/README.md b/integrations/git-sync/README.md
deleted file mode 100644
index c99f1ad4..00000000
--- a/integrations/git-sync/README.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-icon: code-pull-request
-description: >-
- Synchronize your GitBook content with GitHub or GitLab with GitBook’s
- bi-directional integration.
----
-
-# GitHub & GitLab Sync
-
-Git Sync allows technical teams to synchronize GitHub or GitLab repositories with GitBook and turn Markdown files into beautiful, user-friendly docs. Edit directly in GitBook’s powerful editor while keeping content synchronized with your codebase on GitHub or GitLab.
-
-Git Sync is bi-directional, so changes you make directly in GitBook’s editor are automatically synced, as are any commits made on GitHub or GitLab. This allows developers to commit directly from GitHub or GitLab and technical writers, instructional designers and product managers to edit, discuss and feedback changes directly in GitBook.
-
-{% hint style="info" %}
-**Permissions**\
-Administrators and creators can enable and configure Git Sync.
-{% endhint %}
-
-### Product Demo
-
-{% embed url="https://www.youtube.com/watch?v=Ly2zQD0I9bY" %}
-
-### Learn more about
-
-
Enabling GitHub Sync
Learn how to enable the integration if you’re using GitHub
diff --git a/integrations/git-sync/commits.md b/integrations/git-sync/commits.md
deleted file mode 100644
index debe46d9..00000000
--- a/integrations/git-sync/commits.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-layout:
- title:
- visible: true
- description:
- visible: false
- tableOfContents:
- visible: true
- outline:
- visible: true
- pagination:
- visible: true
----
-
-# Commit messages & Autolink
-
-By default, when exporting content from GitBook to the Git repository, GitBook will generate a commit message based on the merged change request:
-
-```
-GITBOOK-14: Improve documentation about users management
-```
-
-## Autolink `GITBOOK-` in GitHub and GitLab
-
-If you want to automatically resolve your GitBook change request IDs (e.g. _GITBOOK-123_) in commits to links, you can enable this using GitHub’s _Autolink references_ feature. See instructions on [GitHub](https://help.github.com/en/github/administering-a-repository/configuring-autolinks-to-reference-external-resources).
-
-Use the following URL format, where `space` corresponds to your space’s URL:
-
-`/`
-
-
-
-
-
-
-
-## Customize the commit message template
-
-When using GitBook with a [monorepo](monorepos.md), or when you have specific guidelines for commit messages; you might want to customize the message used by GitBook when pushing a commit to Git.
-
-The template can contain the following placeholders:
-
-- `{change_request_number}` unique numeric ID for the change request
-- `{change_request_subject}` the subject of the change request when merged, or `No subject` if none has been provided.
-
-The default template is:
-
-```
-GITBOOK-{change_request_number}: {change_request_subject}
-```
diff --git a/integrations/git-sync/content-configuration.md b/integrations/git-sync/content-configuration.md
deleted file mode 100644
index 4ccb8847..00000000
--- a/integrations/git-sync/content-configuration.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# Content configuration
-
-If you’d like to configure GitSync further, you can add a `.gitbook.yaml` file at the root of your repository to tell GitBook how to parse your Git repository.
-
-Here’s an example:
-
-{% tabs %}
-{% tab title=".gitbook.yaml" %}
-```yaml
-root: ./
-
-structure:
- readme: README.md
- summary: SUMMARY.md
-
-redirects:
- previous/page: new-folder/page.md
-```
-{% endtab %}
-{% endtabs %}
-
-## Root
-
-The path to lookup for your documentation defaults to the root directory of the repository. Here’s how you can tell GitBook to look into a `./docs` folder:
-
-{% tabs %}
-{% tab title=".gitbook.yaml" %}
-```yaml
-root: ./docs/
-```
-{% endtab %}
-{% endtabs %}
-
-{% hint style="warning" %}
-**All other options that specify paths will be relative to this root folder**. So if you define root as `./docs/` and then `structure.summary` as `./product/SUMMARY.md`, GitBook will actually look for a file in `./docs/product/SUMMARY.md`.
-{% endhint %}
-
-## Structure
-
-The structure accepts two properties:
-
-* **`readme`**: Your documentation’s first page. Its default value is `./README.md`
-* **`summary`**: Your documentation’s table of content. Its default value is `./SUMMARY.md`
-
-The value of those properties is a path to the corresponding files. The path is relative to the “root” option. For example, here’s how you can tell GitBook to look into a `./product` folder for the first page and summary:
-
-{% tabs %}
-{% tab title=".gitbook.yaml" %}
-```yaml
-structure:
- readme: ./product/README.md
- summary: ./product/SUMMARY.md
-```
-{% endtab %}
-{% endtabs %}
-
-#### Summary
-
-The `summary` file is a Markdown file (`.md`) that should have the following structure:
-
-```
-# Summary
-
-## Use headings to create page groups like this one
-
-* [First page’s title](page1/README.md)
- * [Some child page](page1/page1-1.md)
- * [Some other child page](part1/page1-2.md)
-
-* [Second page’s title](page2/README.md)
- * [Some child page](page2/page2-1.md)
- * [Some other child page](part2/page2-2.md)
-
-## A second-page group
-
-* [Yet another page](another-page.md)
-```
-
-Providing a custom summary file is optional. By default, GitBook will look for a file named `SUMMARY.md` in your `root` folder if specified in your config file, or at the root of the repository otherwise.
-
-If you don’t specify a summary, and GitBook does not find a `SUMMARY.md` file at the root of your docs, GitBook will infer the table of contents from the folder structure and the Markdown files below.
-
-{% hint style="info" %}
-The summary markdown file is **a mirror of the** [**table of contents**](https://docs.gitbook.com/getting-started/overview#table-of-contents) of your GitBook space. So even when no summary file is provided during an initial import, GitBook will create one and/or update it whenever you update your content using the GitBook editor.
-
-Because of this, it’s not possible to reference the same Markdown file twice in your `SUMMARY.md` file, because this would imply that a single page lives at two different URLs in your GitBook space.
-{% endhint %}
-
-## Redirects
-
-While we recommend using [site redirects](../../published-documentation/site-redirects.md) when migrating your content into GitBook, you can also define redirects in your `.gitbook.yaml` configuration file.
-
-{% hint style="info" %}
-Redirects you define in a space’s configuration file are scoped to the corresponding space. We recommend creating [site redirects](../../published-documentation/site-redirects.md) for most cases as they apply to the whole site, across spaces.
-{% endhint %}
-
-#### Restructuring your content in GitBook
-
-When moving your content within GitBook, most URLs should work as expected depending on complexity of the change. There are a number of tools that will allow you to verify which links were broken, if any.
-
-{% hint style="warning" %}
-With Git, when a file is moved many times, the file is removed and a new one is created. This makes it impossible for GitBook to know that a folder has been renamed, for example. Make sure to double-check and add redirects where needed.
-{% endhint %}
-
-### How to create a redirect
-
-You can create custom redirects of a URL to a page by specifying the path to the corresponding file. The path is relative to the “root” option. For example, here’s how you can tell GitBook to redirect users accessing a past url `/help` to a new url `/support`
-
-{% code title=".gitbook.yaml" %}
-```yaml
-root: ./
-
-redirects:
- help: support.md
-```
-{% endcode %}
-
-#### How to redirect on a more complex path:
-
-Original URL: `https://docs.company.com/help` which has now moved to `https://docs.company.com/misc/support` on GitBook.
-
-{% code title=".gitbook.yaml" %}
-```yaml
-root: ./
-
-redirects:
- help: misc/support.md
-```
-{% endcode %}
-
-{% hint style="danger" %}
-The path `misc/support.md` needs to be a real existing path within the repository. It needs to be relative to the current `root` setting in`.gitbook.yaml`.\
-Please don’t add any leading slashes. For example, `./misc/support.md` will not work.
-{% endhint %}
-
-### Troubleshooting
-
-The YAML file needs to be correctly formatted for the redirects to work. Errors such as incorrect indentation or whitespace can result in your redirects not working. [Validating your YAML file](https://www.yamllint.com/) can ensure that the redirects will work smoothly.
-
-It's also important to consider that as long as a page exists for a path, GitBook won’t be looking for a possible redirect. So if you're setting up a redirect for an old page to a new one, you will need to remove the old page in order for the redirect to work.
diff --git a/integrations/git-sync/enabling-github-sync.md b/integrations/git-sync/enabling-github-sync.md
deleted file mode 100644
index 151fdda4..00000000
--- a/integrations/git-sync/enabling-github-sync.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-description: How to set up and authorize the GitHub Sync integration for GitBook.
----
-
-# Enabling GitHub Sync
-
-{% hint style="info" %}
-The GitHub app that powers our GitHub integration is currently not available to customers on GitHub Enterprise Server instances.
-{% endhint %}
-
-### 1. Get started
-
-In the space you want to sync with your GitHub repo, head to the space menu in the top right, and select **Configure**. From the provider list, select **GitHub Sync**.
-
-
Configure GitHub Sync.
-
-### 2. Authenticate with GitHub
-
-If you’re setting up GitHub Sync for the first time and haven’t already linked a GitHub account, you’ll be prompted to do that when you begin configuring Git Sync. If you’ve already linked your account, you might still need to authenticate via GitHub.
-
-{% hint style="warning" %}
-If you see a **'Potential duplicated accounts'** error message at this step, this means your GitHub account is already linked with another GitBook user account.
-
-To help you identify which accounts are linked, you will have to log out from this session and log in using the sign-in with GitHub method. If you already know your GitBook account associated with GitHub you can log into that user account and unlink your GitHub account (done in settings) before logging back in and linking your current account.\
-\
-Read more on our [troubleshooting page](troubleshooting.md#potential-duplicated-accounts-when-signing-in).
-{% endhint %}
-
-### 3. Install the GitBook app to your GitHub account
-
-
Install the GitHub app to your repository.
-
-If you’ve not already done so, you’ll see a prompt to add the [GitBook app](https://github.com/apps/gitbook-com) to your GitHub account. Follow the instructions in the GitHub popover and either give GitBook specific repository permissions, or allow access to all repositories, depending on your needs.
-
-### 4. Select a repository and branch
-
-Select the account and repository you want to keep in sync with your GitBook content.
-
-{% hint style="info" %}
-**Can’t see your repository?** If you can't find your repository in the list, make sure that you've installed the [GitBook GitHub app](https://github.com/apps/gitbook-com) in the right scope (i.e. your personal account or the GitHub org where the repository lives). You should also check that you’ve configured the correct repository access in the GitBook GitHub app.
-{% endhint %}
-
-Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.
-
-### 5. Perform an initial sync
-
-When syncing for the first time, you’ll have the option to sync in one of two directions:
-
-1. Git**Book** -> Git**Hub** will sync your space’s content **to** the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.
-2. Git**Hub** -> Git**Book** will sync your space’s content **from** the selected branch. This is great if you have existing Markdown content in a repository and want to bring it into GitBook.
-
-### 6. Write and commit!
-
-You’re good to go. You’ll notice that if your space was in [live edit](../../content-editor/editing-content/live-edits.md) mode, live edits are now locked. This allows us to reliably sync content to your repository when someone in your team merges a[ change request](../../collaboration/change-requests.md) in GitBook.
-
-When you edit on GitBook, every change request merge will result in a commit to your selected GitHub branch.
-
-When you commit to GitHub, every commit will be synced to your GitBook space as a history commit.
diff --git a/integrations/git-sync/enabling-gitlab-sync.md b/integrations/git-sync/enabling-gitlab-sync.md
deleted file mode 100644
index 4393b03d..00000000
--- a/integrations/git-sync/enabling-gitlab-sync.md
+++ /dev/null
@@ -1,60 +0,0 @@
----
-description: How to set up and authorize the GitLab Sync integration for GitBook.
----
-
-# Enabling GitLab Sync
-
-### 1. Get started
-
-In the space you want to sync with your GitLab repo, head to the space menu in the top right, and select **Synchronize with Git**. From the provider list, select **GitLab Sync**, and click **Configure**.
-
-
Git Sync setup screen
-
-### 2. Generate and enter your API access token
-
-You can generate an API access token in your GitLab user settings.
-
-{% hint style="info" %}
-There are two types of access tokens in GitLab: Project and Personal. Note that in order for the integration to work you’ll need to use a Personal token, which you can generate from your GitLab user preferences menu.
-{% endhint %}
-
-Ensure that you enable the following access for your token:
-
-* `api`
-* `read_repository`
-* `write_repository`
-
-If the tokens you create also have a specific role attached to them, also make sure that it has a `Maintainer` or `Admin` role.
-
-
GitLab setup screen
-
-Then you can paste the token into the API access token field when configuring your GitLab integration.
-
-### 3. Select a repository and branch
-
-Select the repository you want to keep in sync with your GitBook content.
-
-{% hint style="info" %}
-**Can’t see your repository?** Ensure you’ve set the correct permissions when creating your API token.
-{% endhint %}
-
-Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.
-
-{% hint style="info" %}
-For many GitLab repositories, the `main` branch might be automatically set to protected. If this is the case, we recommend adding a specific branch to sync your content between. You can then merge this into `main` and keep the protection in place.
-{% endhint %}
-
-### 4. Perform an initial sync
-
-When syncing for the first time, you’ll have the option to sync in one of two directions:
-
-1. Git**Book** -> Git**Lab** will sync your space’s content **to** the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.
-2. Git**Lab** -> Git**Book** will sync your space’s content **from** the selected branch. This is great if you have existing markdown content in a repository and want to bring it into GitBook.
-
-### 5. Write and commit!
-
-You’re good to go. You’ll notice that if your space was in [live edit](../../content-editor/editing-content/live-edits.md) mode, live edits are now locked. This allows GitBook to reliably sync content to your repository when someone in your team merges a[ change request](../../collaboration/change-requests.md) in GitBook.
-
-When you edit on GitBook, every change request merge will result in a commit to your selected GitLab branch.
-
-When you commit to GitLab, every commit will be synced to your GitBook space as a history commit.
diff --git a/integrations/git-sync/github-pull-request-preview.md b/integrations/git-sync/github-pull-request-preview.md
deleted file mode 100644
index 4bbced55..00000000
--- a/integrations/git-sync/github-pull-request-preview.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# GitHub pull request preview
-
-{% hint style="info" %}
-Customers who configured the GitBook GitHub app before 6th January 2021 and want to enable this feature will need to accept an updated permission request to enable read-only access to PRs. You should have received a notification requesting this access.
-{% endhint %}
-
-When you submit a Pull Request (PR) to a GitHub branch that has been synced to a GitBook space, you can preview the content before merging. This allows you to check the impact of changes before merging them.
-
-You can use this feature to have a final layer of checks before merging a PR, allowing you to see your changes in a non-production environment before merging it into your synced branch.
-
-
Pull-Request preview
-
-### How to access preview links
-
-This behavior works out of the box, provided you have given the [GitBook GitHub app](https://github.com/apps/gitbook-com) the necessary read-only permissions to PRs.
-
-For every PR done using a target branch synced with a GitBook space, you’ll see a status added to the PR with a unique preview URL. Clicking the **Details** link on the status will take you to the preview URL for your content. You can then make sure the content is as expected before merging the PR.
-
-{% hint style="info" %}
-Preview links are only accessible by GitBook users.
-{% endhint %}
-
-### Security considerations
-
-For security reasons, by default GitBook doesn’t currently generate previews for PRs opened from forks of your repository. Because the content of the PR preview is accessible under your own domain, whether on `.gitbook.io` or your [custom domain](../../published-documentation/custom-domain/finalize.md), a user could generate malicious content in a fork of your public repository and have it served under your name.
-
-We allow users to explicitly configure this through an option in the Git Sync settings.
diff --git a/integrations/git-sync/troubleshooting.md b/integrations/git-sync/troubleshooting.md
deleted file mode 100644
index 42f020cb..00000000
--- a/integrations/git-sync/troubleshooting.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# Troubleshooting
-
-## I have a GitHub sync error
-
-In case of errors, make sure that:
-
-* Your repository **has a** `README.md` **file** at its root (or at the `root` folder specified in your `.gitbook.yaml`). This file is required and is used as the homepage for your documentation. For more details, refer to our [content configuration](content-configuration.md).
-* If you have YAML frontmatters in your Markdown files, make sure they are valid using a [linter](http://www.yamllint.com).
-
-## GitBook is not using my `docs` folder
-
-By default, GitBook uses the root of the repository as a starting point. A specific directory can be specified to scope the markdown files. Take a look at our documentation on [content configuration](content-configuration.md) for more details.
-
-## GitBook is creating new markdown files
-
-**When synchronizing and editing from GitBook** with an existing Git repository, GitBook may create new markdown files instead of using the existing ones. This is done to ensure GitBook doesn't overrite files that existed in your repository before.
-
-## My repository is not listed
-
-### For GitHub repositories
-
-Make sure that you have installed the GitBook GitHub app to the correct locations (when installing the app, you can choose to install it to your personal GitHub, or to any organization you have permissions for) and that you have given the app the correct repository permissions.
-
-### For GitLab repositories
-
-Make sure that your access token has been configured with the following access:
-
-* `api`
-* `read_repository`
-* `write_repository`
-
-## Nothing happens on GitBook after adding a new file to my repository
-
-{% hint style="warning" %}
-**This section specifically addresses problems when a `SUMMARY.md` file already exists**
-
-If your repository does not include a `SUMMARY.md` file, GitBook will automatically create one upon the first sync. This means that if you edited your content from GitBook at least once after setting up Git sync, GitBook should have created this file automatically.
-{% endhint %}
-
-If after updating your repository by adding or modifying a markdown file, you do not see the update reflected on GitBook and the sidebar doesn’t indicate an error during the sync, your modified file(s) is probably not listed in [your `SUMMARY.md` file](content-configuration.md#summary).
-
-This could either be because you created the file manually, or because you made an edit on GitBook and the GitBook to Git export phase of the sync created it for you.
-
-The content of this file mirrors your [table of contents](../../content-editor/editor/navigation.md#table-of-contents) on GitBook and is used during the Git to GitBook import phase of the sync to recreate your table of contents and re-conciliate upcoming updates from the repository with your existing content on GitBook.
-
-If after ensuring that all your files are included in the `SUMMARY.md` file there’s still nothing happening on GitBook, don’t hesitate to [contact support](../../help-and-faq/faq/support.md) for assistance.
-
-## GitHub preview is not showing
-
-If your GitHub preview is not showing, it might be because your GitSync integration was configured before January 2022. Versions of GitSync configured before this date do not include GitHub Preview.
-
-You should have received a notification requesting you to accept an updated permission request to enable read-only access to PRs.
-
-In case you did not receive the notification, to troubleshoot you need to update to the new version:
-
-1. Uninstall the GitSync integration from your organization.
-2. Reinstall the new version with the updated permissions.
-
-Please note that uninstalling the GitSync integration will require reconfiguring the integration again on any spaces it was previously connected to.
-
-## Potential duplicated accounts when signing in
-
-This error usually occurs when the GitHub account that you use to set up the sync is already associated with a different GitBook user account.
-
-A good way to identify which GitBook account the GitHub account is already linked to is:
-
-1. Log out from your current GitBook user session (i.e. `name@email.com`)
-2. Log out from any GitHub user sessions.
-3. Go to [the Log in page](https://app.gitbook.com/login).
-4. Select the "Sign in with GitHub" option.
-5. Enter your GitHub credentials.
-6. Once logged in, go to [the account settings](https://app.gitbook.com/account) and either:
- 1. Unlink the account from the "Third-party Login > GitHub" section in the Personal setting
- 2. Delete the account altogether if you do not need it.
-7. Log out from the session.
-8. Log back in using your `name@email.com` GitBook account.
-9. Try to set up Git Sync again.
diff --git a/integrations/github-copilot.md b/integrations/github-copilot.md
index b8df9335..25e9bfb9 100644
--- a/integrations/github-copilot.md
+++ b/integrations/github-copilot.md
@@ -1,11 +1,12 @@
---
icon: github
+description: >-
+ Leverage your GitBook documentation to answer user queries and provide instant
+ responses within your workflow
---
# GitHub Copilot
-
-
### Overview
GitBook Copilot is a powerful tool that helps your team access the knowledge within your organization's documentation effortlessly. By integrating directly with GitHub, it provides relevant answers to queries right in your coding environment.
@@ -14,21 +15,31 @@ Whether you're setting up a new project, troubleshooting code, or exploring your
### Configuration Steps
-#### 1. Install the App
+{% stepper %}
+{% step %}
+### Install the app
-* Install the [GitBook for GitHub Copilot](https://github.com/marketplace/gitbook-for-github-copilot) app in your GitHub organization.
+Install the [GitBook for GitHub Copilot](https://github.com/marketplace/gitbook-for-github-copilot) app in your GitHub organization.
+{% endstep %}
-#### 2. Set Up GitBook Integration
+{% step %}
+### Set up the GitBook integration
-* In your GitBook organization, install the [GitHub Copilot integration](https://app.gitbook.com/integrations/github-copilot).
+In your GitBook organization, install the [GitHub Copilot integration](https://app.gitbook.com/integrations/github-copilot).
+{% endstep %}
-#### 3. Authenticate GitHub
+{% step %}
+### Authenticate your GitHub account
-* Log in to your GitHub account and select the organization(s) for which you want the integration to function.
+Log in to your GitHub account and select the organization(s) for which you want the integration to function.
+{% endstep %}
-#### 4. Connect Your Documentation
+{% step %}
+### Connect your documentation
-* In GitBook’s integration settings, choose which spaces or documentation GitBook Copilot will use to provide answers.
+In GitBook’s integration settings, choose which spaces or documentation GitBook Copilot will use to provide answers.
+{% endstep %}
+{% endstepper %}
### Example Use Cases
@@ -53,8 +64,8 @@ GitBook Copilot answers questions based on your specific documentation. Here are
#### Community Support
-* Engage with other GitBook users in our [GitBook Community](https://github.com/GitbookIO/community).
+Engage with other GitBook users in our [GitBook Community](https://github.com/GitbookIO/community).
#### Technical Support
-* For advanced assistance, contact our team at [support@gitbook.com](mailto:support@gitbook.com).
+For advanced assistance, contact our team at [support@gitbook.com](mailto:support@gitbook.com).
diff --git a/integrations/install-an-integration.md b/integrations/install-an-integration.md
index 3bc1a919..55379a7e 100644
--- a/integrations/install-an-integration.md
+++ b/integrations/install-an-integration.md
@@ -1,42 +1,36 @@
---
icon: puzzle-piece
-description: "How to install an integration in a single space, or all the spaces in your organization —\_and manage its settings"
+description: >-
+ Install an integration in a single space, or all the spaces in your
+ organization
---
# Install and manage integrations
-{% embed url="https://www.youtube.com/watch?v=W6TA9Lftd6A" %}
+There are [many different integrations](https://app.gitbook.com/integrations) available in GitBook. From interactive content blocks to advanced analytics tools, your favorite tools are only a click away from integrating with GitBook.
You can install an integration in a single space, multiple spaces, or all the spaces across your organization.
If you install an integration in a single space, it will only work in that specific space. By installing an integration in multiple spaces, you’ll be able to perform actions across all those spaces.
-### Install an integration in your organization
+
Browse GitBook's built in integration library.
-#### 1. Open the Integrations menu
+### Install an integration in your organization
-Before enabling an integration into a space or site, you'll need to install it in your organization. Start by clicking **Integrations** in the sidebar on the left.
+#### 1. Open the integrations menu
-
Integrations tab
+Before enabling an integration into a space or site, you'll need to install it in your organization. Start by clicking **Integrations** section in the sidebar on the left.
#### 2. Select the integration and install
-Next, click on the integration you want to install on the space (e.g Plausible).
-
-This will open up the integration’s installation screen. Click **Install** to connect it to your organization.
-
-
Integration installation page
-
-From here, the integration will be available to enable in any space or site in your organization.
+Next, click on the integration you want to install. Certain integrations work can be installed for your spaces, and others for your published documentation.
-#### 3. Enable and configure integration
+On this screen you can select the areas you would like to install your integration in.
-The installed installed will now be available in your organization, but you need to enable it on a per-space basis, and you may also need to configure it, depending on the integration
+
Choose an area to install an integration in.
-Firstly, open the integration’s main screen by selecting it on the **Integrations** panel in the app and opening the **Spaces tab**. From here, you can choose which space(s) to enable the integration for.
+#### 3. Configure your integration
-
Enable an integration for a space
+You can now use your integration. Certain integrations may require extra configuration. If so, you’ll see a message asking you to configure your integration in your space or site.
-{% hint style="info" %}
-Certain integrations may require extra configuration. If so, head to the **Organization settings** tab to complete your integration’s configuration.
-{% endhint %}
+View the integration’s instructions to learn more about configuring it for your team.
diff --git a/integrations/integrations-beta/github-entities.md b/integrations/integrations-beta/github-entities.md
index 18144f53..aed5d712 100644
--- a/integrations/integrations-beta/github-entities.md
+++ b/integrations/integrations-beta/github-entities.md
@@ -47,25 +47,25 @@ To configure the GitHub Entities integration, you’ll need to both authenticate
1. **Install the GitHub Entities integration in GitBook**
-
Install the GitHub Entities integration
+
Install the GitHub Entities integration
2. **Install the GitBook Entities app to GitHub**
To configure the GitHub Entities integration correctly, you’ll need to [install the GitBook Entities](https://github.com/apps/gitbook-entities/) app into your GitHub Account.
-
Install the GitBook Entities ap to GitHub
+
Install the GitBook Entities ap to GitHub
3. **Select the repositories you want to sync**
-
Select repositories to index
+
Select repositories to index
4. **Authenticate your GitHub Account**
-
Authenticate your GitHub account
+
Authenticate your GitHub account
5. **Select your account in the GitBook integration’s configuration**
-
Select your GitHub account
+
Select your GitHub account
{% hint style="warning" %}
GitHub Entities will index any and all of the repositories you grant it access to. If you’d only like to index a select few repositories, make sure to configure them as you see in step 3 above.
diff --git a/integrations/integrations-faq.md b/integrations/integrations-faq.md
deleted file mode 100644
index d4b4f781..00000000
--- a/integrations/integrations-faq.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-description: >-
- Find answers to some of the most frequently asked questions on our
- Integrations Platform.
-icon: message-question
----
-
-# Integrations FAQ
-
-## What integrations are available?
-
-We have a number of different verified integrations available from our [marketplace](https://www.gitbook.com/integrations). Visit our listing page to see what integrations you can install.
-
-## Can I build my own integration?
-
-Our integration platform is currently available to anyone with a GitBook account! Head to [our integrations page](https://www.gitbook.com/integrations) or visit our [developer documentation](https://developer.gitbook.com/) to learn more.
-
-## Can I request an integration?
-
-Yes! You can [submit an integration request using this form](https://survey.refiner.io/e61q1m-dp057m). Additionally, you can always head to our [GitBook community](https://github.com/GitbookIO/community) to chat with others about what you’d like to see in GitBook.
-
-## Can I customize GitBook using CSS, JavaScript or other programming languages?
-
-Right now, it’s not possible to customize your GitBook site as you may have seen or heard about in the past. In an earlier and open-sourced version of GitBook this was possible, but with the current version, this functionality was removed.
-
-You can [read more about this change here](https://www.gitbook.com/blog/gitbook-3-0-document-everything-from-start-to-ship).
-
-## What happened to GitBook’s CLI tool?
-
-GitBook’s CLI tool is not currently supported in the latest version of the GitBook platform. Most of the features previously supported by the CLI are now supported by our [GitHub and GitLab Sync integrations](git-sync/).
-
-Content hosted on the [legacy.gitbook.com](https://legacy.gitbook.com/) will continue working until further notice.
diff --git a/integrations/overview.md b/integrations/overview.md
deleted file mode 100644
index d4212c12..00000000
--- a/integrations/overview.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-icon: bullseye-arrow
-description: >-
- Connect your GitBook spaces to your favorite collaboration tools & analytics
- platform
----
-
-# Overview
-
-GitBook integrations allow you to connect your GitBook spaces to some of your favorite platforms and services.
-
-Our [listing page](https://www.gitbook.com/integrations) contains apps and integrations that GitBook and verified developers have created. If you’re interested in developing your own app or integration in GitBook, head to our [developer documentation](https://developer.gitbook.com/) to learn more.
-
-{% hint style="info" %}
-**Permissions**
-
-Creators and admins can install integrations for a space. Only admins can install integrations for an entire organization.
-{% endhint %}
-
-
Installing an integration
Learn how to install an integration for a space or organization.
diff --git a/integrations/slack.md b/integrations/slack.md
index 343ef49a..82ae9724 100644
--- a/integrations/slack.md
+++ b/integrations/slack.md
@@ -1,29 +1,20 @@
---
-icon: slack
description: >-
The GitBook integration for Slack lets you curate knowledge into your
knowledge base, right from the source
hidden: true
-cover: ../.gitbook/assets/Slack (1).png
+noIndex: true
+icon: slack
+cover: broken-reference
coverY: 0
-layout:
- cover:
- visible: true
- size: hero
- title:
- visible: true
- description:
- visible: true
- tableOfContents:
- visible: true
- outline:
- visible: true
- pagination:
- visible: true
---
# Slack (beta)
+{% hint style="warning" %}
+This feature is no longer maintained in GitBook and is subject to change.
+{% endhint %}
+
The GitBook Slack integration helps you collect, review, and share information to and from your company’s knowledge base. With a set of commands you can run within your Slack Workspace, it’s easy to add or use information that’s useful for your team.
GitBook AI will summarize information that you or your team add to your knowledge base, turning a series of messages into a context-rich document. And when you or a colleague need to learn more about something, you can ask GitBook AI and get a plain-text summary, with all the background needed to dive in deeper.
diff --git a/integrations/third-party-integrations.md b/integrations/third-party-integrations.md
deleted file mode 100644
index 582c401d..00000000
--- a/integrations/third-party-integrations.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-icon: plug-circle-check
----
-
-# Third-party Integrations
-
-Third-party integrations are a great way to extend GitBook in different ways, and connect your knowledge with your favorite tools.
-
-You can create your own integrations via GitBook’s integration platform. Visit the [developer documentation](https://developer.gitbook.com/) for more info.
-
-
diff --git a/integrations/visual-studio-code.md b/integrations/visual-studio-code.md
index 8f8503cf..2bc64b9b 100644
--- a/integrations/visual-studio-code.md
+++ b/integrations/visual-studio-code.md
@@ -1,29 +1,20 @@
---
-icon: square-code
description: >-
The GitBook integration for Visual Studio Code allows you to capture and
recall information from your team’s knowledge base.
hidden: true
-cover: ../.gitbook/assets/VS Code (1).png
+noIndex: true
+icon: square-code
+cover: broken-reference
coverY: 0
-layout:
- cover:
- visible: true
- size: hero
- title:
- visible: true
- description:
- visible: true
- tableOfContents:
- visible: true
- outline:
- visible: true
- pagination:
- visible: true
---
# Visual Studio Code (alpha)
+{% hint style="warning" %}
+This feature is no longer maintained in GitBook and is subject to change.
+{% endhint %}
+
The GitBook Visual Studio Code integration allows you to search and ask questions about your documentation and knowledge, directly in your code editor. With a dedicated side panel and a list of different commands, you can easily utilize your entire team’s knowledge directly in the tool you use every day.
### Installation & configuration
@@ -55,5 +46,5 @@ Using the GitBook VS Code extension, you can ask contextual questions in the sid
To summon information, simply open the GitBook panel and type your query into the search bar. You’ll get a summarized result based on information in your GitBook organization.
{% hint style="info" %}
-This feature requires [GitBook AI Search (beta)](../content-editor/searching-your-content/gitbook-ai.md) to be enabled for your organization.
+This feature requires [GitBook AI Search (beta)](../creating-content/searching-your-content/gitbook-ai.md) to be enabled for your organization.
{% endhint %}
diff --git a/product-tour/git-sync/monorepos.md b/product-tour/git-sync/monorepos.md
index adc99e45..92b09873 100644
--- a/product-tour/git-sync/monorepos.md
+++ b/product-tour/git-sync/monorepos.md
@@ -6,7 +6,7 @@ GitBook can synchronize multiple directories from the same repository with multi
-
Monorepo preview
+
Monorepo preview
diff --git a/product-tour/navigation.md b/product-tour/navigation.md
index 33b8fa68..64a98e98 100644
--- a/product-tour/navigation.md
+++ b/product-tour/navigation.md
@@ -60,7 +60,7 @@ The space header is a narrow area at the very top of the GitBook app. It include
- **The share menu**\
From here you can select a [visibility option](../publishing/share/space-publishing.md) for your space and, once a space is published, access the link and custom domain settings for the space.
- **The edit button**\
- Click this to start a new [change request](https://docs.gitbook.com/getting-started/collaboration/change-requests).
+ Click this to start a new [change request](https://gitbook.com/docs/collaboration/change-requests).
- **The space actions menu**\
The icon with three vertical dots in the very top-right corner opens up a number of actions for the space.
@@ -154,7 +154,7 @@ Page actions are located next to the page title. The type of actions available w
-
Page options menu
+
Page options menu
diff --git a/product-tour/searching-your-content/lens.md b/product-tour/searching-your-content/lens.md
index ab8ae2f3..619dc2e1 100644
--- a/product-tour/searching-your-content/lens.md
+++ b/product-tour/searching-your-content/lens.md
@@ -40,7 +40,7 @@ Then, click on the GitBook AI tab. You’ll see a number of suggested questions
-
Ask a question with GitBook AI.
+
Ask a question with GitBook AI.
@@ -48,7 +48,7 @@ For this example, lets try: "What makes change requests a powerful GitBook featu
-
GitBook AI gives you a semantic answer to your question.
+
GitBook AI gives you a semantic answer to your question.
diff --git a/product-tour/sso-and-saml/saml/README.md b/product-tour/sso-and-saml/saml/README.md
index 545313bb..b3cccd09 100644
--- a/product-tour/sso-and-saml/saml/README.md
+++ b/product-tour/sso-and-saml/saml/README.md
@@ -24,7 +24,7 @@ After configuring SSO on your IdP, you will be able to enter metadata. When the
-
+
@@ -41,7 +41,7 @@ Most SAML 2.0 compliant identity providers require the same information about th
-
+
diff --git a/product-tour/sso-and-saml/saml/sso-members-vs-non-sso.md b/product-tour/sso-and-saml/saml/sso-members-vs-non-sso.md
index f89e8eb8..9c011b65 100644
--- a/product-tour/sso-and-saml/saml/sso-members-vs-non-sso.md
+++ b/product-tour/sso-and-saml/saml/sso-members-vs-non-sso.md
@@ -4,7 +4,7 @@ Users who have created a GitBook account with an email used in your SAML Identit
-
Login with SSO screen
+
Login with SSO screen
@@ -41,6 +41,6 @@ to Organization administrators can enable SSO login for members by linking their
-
+
diff --git a/published-documentation/custom-domain/README.md b/published-documentation/custom-domain/README.md
deleted file mode 100644
index 75bef4d3..00000000
--- a/published-documentation/custom-domain/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-description: Learn how to set a custom domain for your GitBook organization or Docs sites
-icon: globe-pointer
----
-
-# Set a custom domain
-
-By default, your sites are accessible on a `[subdomain].gitbook.io` domain.
-
-You can customize this by setting a custom domain, meaning your audience can access your documentation on a chosen domain.
-
-{% hint style="info" %}
-**Permissions**
-
-**Organization-level** domains can be set by users with admin rights.\
-**Site** domains can be set by users with creator or admin rights.
-{% endhint %}
-
-### Learn more about:
-
-
Choose a subdomain and its location
Set a custom subdomain for your published content.
diff --git a/published-documentation/custom-domain/choose.md b/published-documentation/custom-domain/choose.md
deleted file mode 100644
index 15a922a9..00000000
--- a/published-documentation/custom-domain/choose.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-layout:
- title:
- visible: true
- description:
- visible: true
- tableOfContents:
- visible: true
- outline:
- visible: true
- pagination:
- visible: true
----
-
-# 1. Choose a subdomain and its location
-
-Here are some examples of domains you can set in GitBook.
-
-| Domain type | Example | Supported? |
-| ---------------- | ------------------------------------------------------------------------------------------------------------- | :--------: |
-| Apex domain | `example.com` | ❌ |
-| `www` subdomain | `www.example.com` | ✅ |
-| Custom subdomain |
docs.example.com
help.example.com anything.example.com
| ✅ |
-
-## Decide where to set the custom domain
-
-There are two levels at which a custom domain can be set:
-
-1. At the **organization level**
-2. At the **docs site** level
-
-{% hint style="warning" %}
-**Your URL path will depend on where you set the domain.**
-{% endhint %}
-
-## Organization custom domains
-
-Because organizations can contain many sites (and internal spaces) any custom domain set for the organization will apply to all published sites unless overridden.
-
-{% hint style="info" %}
-Each published site will follow after your organization's domain
-
-**`Org-domain/site-name/page-group/page`**
-{% endhint %}
-
-If you’ve decided that you want to set a custom domain at the organization level, you can [go to the next step](organization-level-custom-domain.md) for details on how to set it. If you’re not sure, keep reading to review your other options.
-
-## Site custom domains
-
-If you want to set up a domain different from your main organization domain, or you want to maintain a shorter URL path, you should set the domain directly at a site level.
-
-For example, the domains set for _Site A_ and _Site B_ could be:
-
-* `site-a-domain/page-group/page`
-* `site-b-domain/page-group/page`
-
-{% hint style="info" %}
-Domains set at a site level will have the following path
-
-If no page groups are used: **`site-domain/page`**
-
-(Or, if page groups are used:**`site-domain/page-group/page)`**
-{% endhint %}
diff --git a/published-documentation/custom-domain/configure-dns.md b/published-documentation/custom-domain/configure-dns.md
deleted file mode 100644
index acc39dca..00000000
--- a/published-documentation/custom-domain/configure-dns.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# 3. Configure the DNS
-
-Configuring DNS happens _outside_ of GitBook, at the DNS provider you are using for your domain.
-
-There are three parts to this step:
-
-1. [Configure a CNAME record](configure-dns.md#configure-a-cname-record)
-2. [Check for a CAA record](configure-dns.md#check-for-a-caa-record)
-3. [Wait for the changes to take effect](configure-dns.md#wait-for-the-changes-to-take-effect)
-
-## Configure a CNAME record
-
-The names of the fields and what to enter to configure the record may differ between DNS control panels, but we’ve covered the most common options here. If you’re in any doubt, check with your DNS provider.
-
-* The **type** is the kind of DNS record that you want to create. Here, you need to choose **CNAME**.
-* The **name** or **DNS entry** is where you enter your subdomain. You might need to enter it in full (e.g. **docs.example.com**) or you might need to enter the part before your apex domain (e.g. **docs**). If you’re unsure which to use, check with your DNS provider.
-* The **target, value** or **destination** is where the subdomain should be pointed.
-
-{% hint style="info" %}
-You might also see a field named **TTL**, which stands for Time To Live. It’s the number of seconds that the DNS record can be cached for.
-
-To determine an appropriate TTL (Time to Live) for your new DNS records, you can reference the TTL values of your existing records. Matching these values is a safe practice if you're unsure of what to set for the new ones.\
-\
-Alternatively, we suggest setting 43200 seconds (12 hours) or 86400 seconds (24 hours).
-{% endhint %}
-
-Here’s an example of how a correct configuration looks in Cloudflare’s control panel:
-
-
-
-{% hint style="danger" %}
-**Note:** a CNAME record cannot co-exist with another record for the same name. If you already have an A record, AAAA record, TXT record, or any other type of record for your chosen subdomain, you would need to remove those, before adding the CNAME record.
-{% endhint %}
-
-### Are you using Cloudflare?
-
-If you are configuring DNS in Cloudflare’s control panel, please ensure that Cloudflare’s proxying (the orange cloud, also called "Proxy status" in your domain settings) is **disabled**.
-
-This is for two reasons:
-
-1. This option obfuscates the DNS target for your domain to the public, preventing GitBook from properly running routine checks on your custom domain.
-2. Your custom domain will already benefit from Cloudflare’s CDN and a Google Trust Services SSL certificate on our end.
-
-Again, please **turn off Cloudflare proxying** to ensure that your documentation is served without issues and can be monitored by GitBook.
-
-{% hint style="warning" %}
-**GitBook does not officially support proxy setups**
-
-If you decide to set it up anyway, please ensure your setup respects the following:
-
-* You need to proxy all `GET`, `OPTIONS`, `HEAD`, `POST` methods.
-* You should respect the `Cache-Control` header and use the entire request (URL + headers, by respecting the `Vary` header) as a cache key.
-* You should not modify the HTML to load external resources, or you should consider the CSP and ensure a [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global\_attributes/nonce) is set on every resource.
-{% endhint %}
-
-## Check for a CAA record
-
-CAA records enable you to specify who can issue an SSL certificate for the domains you own. We use Google Trust Services to issue an SSL certificate for your custom domain, so this needs to be allowed. There are two ways to do this:
-
-1. Have no CAA record. Without a CAA record, there are no limitations on which SSL providers can issue an SSL certificate for your domain.
-2. Have a CAA record that explicitly allows Google Trust Services. If a CAA record exists, any providers not explicitly allowed will be blocked. The following is the value that would need to be included in a CAA record to allow Google Trust Services:
-
-```
-0 issue "pki.goog"
-```
-
-## Wait for the changes to take effect
-
-DNS records are cached for a defined period, known as the Time to Live (TTL). This caching is beneficial for performance since DNS records rarely change.
-
-The Time to Live (TTL) value specifies when DNS cache servers must refresh their cache by checking for updates, ensuring they respond with the most current information.
-
-In most cases, it’s best to allow _**at least an hour**_ before moving to the final step of custom domain set-up.
-
-{% hint style="info" %}
-**You might need to wait 1-48 hours for the DNS changes to take effect.**
-{% endhint %}
-
-#### Want to check how this process, known as _propagation_, is progressing?
-
-You could use a DNS lookup tool, such as [WhatsMyDNS](https://www.whatsmydns.net/).
-
-Enter your full subdomain, select CNAME from the dropdown list, and press the Search button. DNS cache servers around the world will respond to let you know what their cached result is. You’ll want to periodically check these results until the majority respond with your assigned CNAME value.
-
-Once DNS propagation has been completed, you can move on to the last step: [confirming the custom domain setup](finalize.md).
diff --git a/published-documentation/custom-domain/finalize.md b/published-documentation/custom-domain/finalize.md
deleted file mode 100644
index 80aa9f2c..00000000
--- a/published-documentation/custom-domain/finalize.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# 4. Finalize the custom domain setup
-
-Once your CNAME record is successfully added within your DNS settings through your DNS provider, you can continue the domain connection process in GitBook.
-
-### Finalize the domain setup
-
-After completing the second and third steps, the **Configure your DNS** screen should let you advance by clicking **Ready: Go Live.** This starts GitBook’s validation process.
-
-
-
-
-
-
-
-During this phase, GitBook verifies your CNAME record and configures the SSL certificate for your domain, ensuring a secure connection.
-
-
-
-When this process is finished, a success notification confirms that your site is live. Although this process generally proceeds without issues, occasional errors can occur.
-
-
-
-{% hint style="warning" %}
-Should you encounter any challenges, make a note of the error and refer to our [troubleshooting guide](https://docs.gitbook.com/published-documentation/custom-domain/troubleshooting). If troubleshooting doesn’t work or the issue isn’t addressed in our guide, don't hesitate to [contact our support team](https://www.gitbook.com/contact) for assistance.
-{% endhint %}
diff --git a/published-documentation/custom-domain/organization-level-custom-domain.md b/published-documentation/custom-domain/organization-level-custom-domain.md
deleted file mode 100644
index 97e5d6f0..00000000
--- a/published-documentation/custom-domain/organization-level-custom-domain.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# 2. Initiate the custom domain set-up
-
-Custom domain set-up steps for organizations and sites are similar but will impact your future published URL path. This is why it's important that you decide where to set the domain and follow the correct guide below.
-
-## Guide for organization domains
-
-You’ll find the options for setting a custom domain for an organization within the organization settings page. Open the **Settings** menu in the lower left corner, and click on **Organization** **Settings**.
-
-1. In the **General** section, scroll to the **Publishing** section and under **Custom Domain**, click **Connect a domain**
-
-
Set a domain for your entire organization in settings.
-2. This will open a window where you can enter the custom domain, then click **Next: Configure DNS**
-
-
-
-
Connect a custom domain
-
-
-3. The final step requires you to copy the name and value to your clipboard so that you can create a CNAME DNS record. To copy the information click on the icon on the right-hand side of each field. Once copied, you can move on to [configuring the DNS](configure-dns.md).
-
-
-
-
The name and value for the CNAME record
-
-
-
-{% hint style="info" %}
-The value for the CNAME record will be in the format:\
-`[example]-hosting.gitbook.io`\
-\
-Please use the value displayed in the GitBook app and _not_ the value in the screenshot above.
-{% endhint %}
-
-Now you’re ready to move on to the next step: [configuring the DNS](configure-dns.md).
-
-## Guide for site domains
-
-The method for configuring a site domain typically mirrors the approach for setting up an organization domain. The primary distinction lies in step 1 which is the initial location for initiating the custom domain configuration.
-
-1. Navigate to the site for which you want to set the custom domain. Click **Settings** then choose **Set up a custom domain**
-
-
-
-2. This will open a window where you can enter the custom domain, then click **Next: Configure DNS**
-
-
-
-3. The final step requires you to copy the name and value to your clipboard so that you can create a CNAME DNS record. To copy the information click on the icon on the right-hand side of each field. Once copied, you can move on to [configuring the DNS](configure-dns.md).
-
-{% hint style="info" %}
-The value for the CNAME record will be in the format:\
-`[example]-hosting.gitbook.io`\
-\
-Please use the value displayed in the GitBook app and _not_ the value in the screenshot above.
-{% endhint %}
-
-Now, you’re ready to move on to the next step: [configuring the DNS](configure-dns.md).
diff --git a/published-documentation/custom-domain/troubleshooting.md b/published-documentation/custom-domain/troubleshooting.md
deleted file mode 100644
index fc7cc963..00000000
--- a/published-documentation/custom-domain/troubleshooting.md
+++ /dev/null
@@ -1,77 +0,0 @@
----
-description: >-
- Helping you to solve some of the most common issues when setting up a custom
- domain.
----
-
-# Troubleshooting custom domain setup
-
-Setting up a custom domain can occasionally run into obstacles. Below, we outline frequent problems encountered during this process and provide detailed solutions to each of them.
-
-
-
-SSL error: an error occurred when provisioning your SSL certificate.
-
-When a custom domain is set for your organization, collection, or space, we set up an SSL certificate on our end so that your documentation will load securely, over HTTPS. \
-\
-This happens automatically when you set your custom domain — you do not need to purchase or configure an SSL certificate.
-
-Occasionally errors occur at this stage, usually when the CNAME record for the custom domain hasn't propagated.
-
-In these cases, we can recommend the following:
-
-1. Check that your CNAME record is set up correctly. \
- Please review our page about [configuring DNS](configure-dns.md) to help you with this. \
- If the CNAME record is incorrect, we won't be able to configure the SSL certificate and complete the custom domain set-up.
-2. Allow _**at least one hour**_ between [configuring the CNAME record](configure-dns.md) and [finalizing the custom domain setup](finalize.md).
-3. Verify if the CNAME has propagated. You can try using a third-party DNS lookup tool, such as [WhatsMyDNS](https://www.whatsmydns.net/), to find out what the servers believe to be correct for your correct CNAME record.
-4. If you are using Cloudflare, please confirm that you don’t have the record proxied [as explained here](configure-dns.md#are-you-using-cloudflare).
-
-
-
-
-
-Domain already connected error: your subdomain is already configured for different content.
-
-A custom domain assigned to an organization or site must be unique. Attempting to use the same custom domain in more than one location will result in an error.
-
-If this happens, you can click the link within the error message to look at the content the custom domain is already connected to. This may help you to decide what to do next.\
-It’s also possible that you might not have access to the content — if that’s the case, [contact the support team](../../help-and-faq/faq/support.md) and they can help you with your next steps.
-
-The solution to this error will always be one of two things, however:
-
-1. Choose a different custom domain; or
-2. Disconnect the custom domain from the content it is already connected to, then reconnect it to the new content.
-
-
-
-
-
-The custom domain is set correctly, but is redirecting to a different custom domain.
-
-This is an expected behaviour, that usually can be changed.
-
-The common issue is that custom domains have been set in multiple locations for example organization and the site. When someone accesses the URL for an organization, they are taken straight to the organization’s default content. Likewise, when someone accesses the URL for a multi-variant site, they are taken straight to the multi-variant default site.
-
-**Example**
-
-* `docs.example.com` is set as the custom domain for an organization
-* `team.example.com` is set as the custom domain for that organization’s default content.
-
-In this case, the expected behaviour would be `docs.example.com` redirecting you to `team.example.com`.
-
-This issue can be solved by changing the default content or by removing the organization domain and adding the domains at a space level or the other way around (removing the space domain, and maintaining the org domain)
-
-This issue frequently occurs due to the confusion over the location of the domain. \
-Please ensure you checked where your domains are set up, and adjusted this to your requirement.
-
-
-
-{% hint style="info" %}
-[Contact the support team](../../help-and-faq/faq/support.md) if you are still experiencing an issue.
-
-In your message, please make sure to share:
-
-1. The subdomain that you would like to set as a custom domain
-2. The organization or site name for which you would like to set it.
-{% endhint %}
diff --git a/published-documentation/customization/README.md b/published-documentation/customization/README.md
deleted file mode 100644
index 85a5ac5c..00000000
--- a/published-documentation/customization/README.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-icon: palette
-description: >-
- Change the look and feel of your published docs site by adding a custom logo,
- changing theme colors and personalizing the footer to align your site with
- your brand.
----
-
-# Customization
-
-{% embed url="https://www.youtube.com/watch?v=h-Zp3SuQvPo" %}
-
-You can customize the appearance of your published documentation, match the user interface to the language of your content, and more.
-
-You can apply customizations to your entire docs site as a site-wide theme, or to individual [variations](../site-structure-and-navigation/publish-multiple-spaces-on-one-site.md) using overrides.
-
-{% hint style="info" %}
-**Permissions**
-
-Admins and creators in a space published as part of a docs site can edit customization settings.
-{% endhint %}
-
-### Learn more about
-
-
diff --git a/published-documentation/customization/collection-customization.md b/published-documentation/customization/collection-customization.md
deleted file mode 100644
index a829cc99..00000000
--- a/published-documentation/customization/collection-customization.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-description: Customize individual spaces within your published docs site.
----
-
-# Customizing sites with multiple spaces
-
-If you have [a docs site with more than one linked space](../site-structure-and-navigation/publish-multiple-spaces-on-one-site.md), you can control the customization of each variation individually.
-
-### How is customizing a linked space different from customizing a docs site?
-
-Customizing an individual linked spaces lets you control the appearance of different parts of your published documentation. This is useful if you want to have different styles for different products or experiences that live on the same docs site.
-
-
Customize published docs with multiple linked spaces
-
-### Overriding site-wide settings
-
-Changes you make at a site-wide level will automatically apply to all linked spaces.
-
-However, you can also choose specific linked spaces from the drop-down menu in the **Customization** panel, and apply overrides to those linked spaces.
-
-Changes you make here will override the site-wide customization settings, even if you change the site-wide setting again later.
-
-{% hint style="info" %}
-Most customization settings apply to your **published content**. This keeps your writing experience and in-app GitBook content consistent while allowing you to control the output to a degree.
-{% endhint %}
-
-### Customization options
-
-To learn more about each of the customization options read the guidance on [site customization](space-customization.md).
diff --git a/published-documentation/customization/page-layouts.md b/published-documentation/customization/page-layouts.md
deleted file mode 100644
index 02fdefad..00000000
--- a/published-documentation/customization/page-layouts.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-coverY: 0
----
-
-# Page options & covers
-
-You can customize the look and feel of individual pages within a space. You can open the **Page options** menu or change a page’s cover by hovering over the page title. You’ll see the buttons appear just above the page title.
-
-
Page options
-
-### Page options
-
-In the Page Options side panel, you can select how each page is displayed to those who visit your **published** content. There are three layout presets to choose from, or you can create a custom layout.
-
-Each layout preset will toggle on or off each of the following parts of the page:
-
-* Page title
-* Page description
-* Table of contents
-* Page outline
-* Next/previous links
-
-Take a look at how each preset will set each of these parts of the page:
-
-
Part of the page
Docs layout
Editorial layout
Landing page layout
Page title
true
true
true
Page description
true
true
true
Table of contents
true
false
false
Page outline
true
true
false
Next/previous links
true
true
true
-
-If you want to use a custom layout, you can choose simply toggle a setting in any preset to switch the setting to **Custom** — or manually select the **Custom** option from the drop-down and start making changes.
-
-{% hint style="info" %}
-Remember that the settings you choose here will affect **published content only**.
-{% endhint %}
-
-### Page covers
-
-You can also set a page cover for each page of your documentation. When you click the **Page cover** option, a default cover will be added immediately. From there, you can:
-
-* **Change the cover image**
-
- Hover over the page cover and click **Change cover**, then select or upload an image. Based on how we currently display page covers, 1990x480 pixels is the ideal size.
-* **Reposition the cover image**
-
- Hover over the page cover and open the **Actions menu** . Click **Reposition**, then drag the image as you wish and click **Save**.
-* **Remove the cover image**\
- Hover over the page cover and open the **Actions menu** , then click **Remove**.
-* **Full width and hero width**\
- You can change the style of your page cover to span the full width of your screen or just the width of your content. Hover over the page cover and open the **Actions menu** , then choose your preferred option from the menu.
diff --git a/published-documentation/customization/space-customization.md b/published-documentation/customization/space-customization.md
deleted file mode 100644
index 2a70b9df..00000000
--- a/published-documentation/customization/space-customization.md
+++ /dev/null
@@ -1,184 +0,0 @@
----
-description: Customize a published GitBook site.
----
-
-# Site customization
-
-Customizing your site lets you control the branding, presentation and extra features of your site's public content. You can access your site's customization settings from the settings tab from your docs site's overview page.
-
-{% hint style="info" %}
-Most customization settings apply to your **published content**. This keeps your writing experience and in-app GitBook content consistent while allowing you to control the appearance of your published content.
-{% endhint %}
-
-
Customize options
-
-{% hint style="info" %}
-[Advanced customization](space-customization.md#what-counts-as-advanced-customization) settings are only available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing) or scroll down to find out what’s included in Advanced customization.
-{% endhint %}
-
-### General
-
-Control how your content looks in the General tab. The available options are:
-
-
-
-Title, icon and logo
-
-**Title**\
-You can set any title you choose for your space. Note: this setting will only affect the title that displays _in the published documentation_. If you want to edit the title in the GitBook app, close the customize menu and edit it at the top of the space.
-
-**Icon**\
-You can set an emoji, or upload an icon of your own. Note: this setting will only affect the icon that displays _in the published documentation_ and it’ll also be used as the favicon for the page. If you want to edit the icon used within the GitBook app, close the customize section and click on the icon at the top of the space.
-
-**Custom logo** Premium & Enterprise\
-You can replace _both_ the published space’s title and icon with a custom logo so that your documentation better reflects your own branding — and, you can upload two versions: one for light mode, and one for dark mode.
-
-#### What’s the difference between the icon and logo options?
-
-The icon setting lets you upload a small, 132x132px image, which will appear _alongside_ your space title. The custom logo option lets you upload a larger image (we recommend at least 600px wide), which will completely replace any icon and title you’ve set.
-
-
-
-
-
-Themes (for light & dark modes)
-
-Themes let you customize the color scheme of your published content for both light and dark mode. While you can use any colors you like, it’s important to keep accessibility in mind and choose something with good contrast so your content is easy to read.
-
-**Default theme**\
-All spaces have access to this theme, where the header background color will be aligned with the background color for the rest of the space.
-
-**Bold theme** Premium & Enterprise\
-The bold theme uses the primary color as the header background color.
-
-**Contrast theme** Premium & Enterprise\
-The contrast theme has a dark header background color in light mode, and a light header background color in dark mode.
-
-**Custom theme** Premium & Enterprise\
-The custom theme option lets you to set your own color preferences for the background color and link color in the header, in addition to choosing the primary color for light and dark mode.
-
-
-
-
-
-Modes
-
-**Show mode toggle**\
-Enable this if you would like visitors to your published content to be able to manually toggle between light and dark mode. Readers can find the toggle at the bottom of any published page, both on larger screens and mobile devices.
-
-**Default mode**\
-Choose whether visitors to your published content will see it in light or dark mode initially. If **Show mode toggle** is enabled, they’ll be able to switch to the other option if they prefer. If **Show mode toggle** is disabled, they’ll only be able to see your content in the mode you choose here.
-
-_Note: if you just want to change the theme within the GitBook app, you can do that from your **Settings**_ _menu, which can be found at the bottom of the_ [_sidebar_](../../content-editor/editor/navigation.md#sidebar)_._
-
-
-
-
-
-Styling
-
-**Font family** Premium & Enterprise\
-You can choose a font family for your published content from a list of popular options.
-
-GitBook doesn’t support uploading or linking custom fonts. If you think we’re missing a typeface that works wonderfully for headers, body copy, and captions, [let us know](../../help-and-faq/faq/support.md)!
-
-**Corner style**\
-Choose either a rounded or straight corner style, to help align your published GitBook content with your own brand’s styling preferences.
-
-**Background**\
-Switch between a plain background and a subtly tinted background that complements your [theme](space-customization.md#themes-for-light-and-dark-modes).
-
-
-
-### Layout: manage navigation options for your content
-
-
-
-Header
-
-**Navigation**\
-Add header links to your site. You could use header links to point to important parts of your documentation, or perhaps to link back to your main website.
-
-You can choose what type of appearance you would like your link to have, and can choose between a normal link, primary button, and secondary button
-
-When enabled, simply add a title and a URL for each link. We support two levels of header navigation, meaning that you can have sub-links that appear in a dropdown menu.
-
-.png>)
-
-
-
-
-
-Page
-
-**Pagination**\
-Keep this setting on to have previous and next buttons appear at the bottom of each page in your space, or toggle it off to remove them.
-
-
-
-
-
-Footer Premium & Enterprise
-
-Enable or disable a footer section for your space.
-
-**Logo** Premium & Enterprise\
-Add your logo or another image in the footer.
-
-**Copyright text** Premium & Enterprise\
-Add some brief copyright information to your footer.
-
-**Navigation** Premium & Enterprise\
-Add links in your footer, in multiple sections. Just like with the header, you can add a title and URL for each link. Make sure to also include a section title for each section you create.
-
-
-
-### Configure: manage the interface
-
-
-
-Localize user interface
-
-You can select from a list of languages to localize the user interface of your published content. This will apply translations to the **non-custom** areas of the interface.
-
-This setting will _not_ auto-translate your actual content, but can help with matching the user interface to the language that you are writing in.
-
-Is there a language we don’t yet offer that you would like to see included in this list? [Let us know](https://github.com/GitbookIO/gitbook/issues), or [contribute your own translation](https://www.gitbook.com/solutions/open-source)!
-
-
-
-
-
-Privacy Policy
-
-You can link to your own privacy policy to help visitors understand how your GitBook content uses cookies, and how you protect their privacy. If you choose not to set one, your site will default to [GitBook’s own privacy policy](https://policies.gitbook.com/privacy-and-security/statement/cookies).
-
-
-
-
-
-Edit on GitHub/GitLab
-
-If your space is connected to a Git repository, you can optionally show a link for your users to contribute to your documentation from your linked repository.
-
-
-
-### What counts as ‘Advanced customization’?
-
-Every GitBook user can take advantage of basic customization options on their docs site. Pro or Enterprise plan users can also use advanced customization features to further tweak their docs to match their brand.
-
-Advanced customization options include:
-
-* **Custom logo** – Add a logo that replaces the emoji and title at the top of your docs site.
-* **Custom font** – Change the font of your docs to one of the built-in options.
-* **Footer** – Add a custom logo, copyright text and navigation to a footer at the bottom of your documentation.
-* **Bold, Contrast and Custom themes** – Customize the primary color of your docs, as well as setting the background color for your header and the links within it.
-* **Ask GitBook AI** – Let your users ask anything about your product from the Search menu. GitBook AI will scan your documentation and provide a plain English answer in seconds.
-
-### What _cannot_ be customized?
-
-The options above provide lots of ways for you to customize your space, but there are a few things that you won’t be able to customize, regardless of [your chosen plan](../../account-management/plans/).
-
-1. It’s not possible to customize the layout of the elements on the page. (However, it _is_ possible to [hide certain elements](page-layouts.md) on a page-by-page basis)
-2. There’s no way to insert custom code, such as CSS, HTML, JS, etc., directly into one or more documentation pages. If you’re looking to integrate a third party service, take a look at [the docs for our integrations platform](https://developer.gitbook.com/). We already integrate with a number of popular tools, and offer [rich embeds](../../content-editor/blocks/embed-a-url.md) for many more.
-3. It’s not possible to remove the small "Powered by GitBook" link that appears in published documentation.
diff --git a/published-documentation/insights.md b/published-documentation/insights.md
deleted file mode 100644
index 0536055c..00000000
--- a/published-documentation/insights.md
+++ /dev/null
@@ -1,60 +0,0 @@
----
-icon: chart-line-up
----
-
-# Site insights
-
-{% hint style="info" %}
-This feature is available as part of the Premium and Ultimate sites plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-Insights give you information on the content you've published and how it performs. It's split up between three sections — **traffic**, **search** and **feedback**.
-
-You can find insights for individual docs sites in the docs site dashboard, and can sort it by the last week, month and year.
-
-
-
-### Traffic
-
-GitBook tracks page views to help you understand the popularity and reach of your content. Each time a user visits a page on your docs site, it is counted as a page view.
-
-This information is compiled and displayed in the Traffic section of the Insights tab, allowing you to identify which pages are most visited and engage the most readers. Page views are critical for assessing the effectiveness of your content strategy and optimizing your documentation based on user interest.
-
-### Search
-
-You can measure and improve your documentation by checking which keywords are used the most by users searching your documentation.
-
-Switch to the **Search analytics** tab to see what keywords are performing the best, and which ones you could improve on. You can view these search terms for the past week, month, or year.
-
-The information here can be helpful for informing your content architecture, making certain parts of your documentation easier to find without search, or adding additional content to existing pages based on what your visitors are searching for.
-
-If you want to use or analyze this data further outside of GitBook, click **Download CSV** to download a `.csv` file to your device.
-
-You’ll get information on:
-
-`pageHits`: Total number of pages (title and description) matching the search term/query .
-
-`sectionHits`: Total number of sections (contents of the pages) matching the search term/query.
-
-### Feedback
-
-Content scores give you a high-level representation of how your users rate your content. After enabling [page rating](site-settings.md#page-ratings-pro-and-enterprise-plans) in the **Customize** menu for a site, you can see each page’s average feedback rating here.
-
-You’ll initially see the ratings for your site’s default content, and you can use the dropdown menu on the right to select any other linked spaces in that site. You can then hover over the average rating to see how many positive, neutral and negative ratings a specific page has.
-
-If you want to use or analyze this data further outside of GitBook, click **Download CSV** to download a `.csv` file to your device.
-
-#### How does GitBook calculate user scores?
-
-GitBook uses a simple formula to calculate the page’s overall score:
-
-`no. of ratings * (no. of positives - [0.5 * no. of neutrals] - [2 * no. of negatives])`
-
-The goal of the content score is to surface the pages with the most feedback, with a bias towards negative ratings so you can see pages that need improvements. The more ratings a page has, the more the formula amplifies the sentiments of those ratings. This helps you spot pages that need attention, as well as pages that are highly-rated — to help you identify, iterate on and replicate your best content.
-
-We cap the score at 500 (and -500) to avoid scores for commonly-rated pages reaching 10,000+.
-
-{% hint style="info" %}
-**Why can’t I see any data for my site?**\
-We only display data for published sites with page ratings enabled. If your site is not published or does not have page ratings enabled, you won’t see any insights.
-{% endhint %}
diff --git a/published-documentation/overview.md b/published-documentation/overview.md
deleted file mode 100644
index b9853a35..00000000
--- a/published-documentation/overview.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-icon: bullseye-arrow
-description: Publish and share your content with internal or external audiences.
----
-
-# Overview
-
-When you’re ready to share your work, you’re able to publish your content so others can view and interact with the things you’ve created.
-
-Below we’ll explain how to publish your content as a docs site, and invite teammates and users to collaborate on editing your content.
-
-
diff --git a/published-documentation/publish-a-docs-site/README.md b/published-documentation/publish-a-docs-site/README.md
deleted file mode 100644
index 4a26f553..00000000
--- a/published-documentation/publish-a-docs-site/README.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-icon: globe
----
-
-# Publish a docs site
-
-Once you’ve finished writing, editing, or importing your content, you can publish your work to the web as a docs site. Your docs will be published on the web and available to your selected audience.
-
-To get started, create a new docs site for your content to live on, or publish a space as a docs site.
-
-### Create a docs site
-
-{% embed url="https://www.youtube.com/watch?v=oTOEeqU4qk8" %}
-
-To create a docs site, click the plus **+** icon next to Docs site in the sidebar on the left.
-
-The content on your site comes from [spaces](../../content-editor/editor/content-structure/what-is-a-space.md) in your organization. When you create a new docs site, you can create a new space, or link an existing one.
-
-After linking a space, you'll be able to choose who can access your content once it’s published.
-
-
Docs site home
-
-Alternatively, you can create a docs site from the space you want to publish by opening the space and clicking **Share** in the top-right corner of the window. Then choose **Publish as a docs site** in the share modal’s sidebar.
-
-From this menu, you can link your space to an existing docs site, or create a new one to publish your space on its own. It also shows any other docs site your space is already linked to.
-
-### Delete or unpublish a docs site
-
-To delete a docs site, you'll need to go into your site's settings. See [site-settings.md](../site-settings.md "mention") for more information.
-
-### Publish your content
-
-
diff --git a/published-documentation/publish-a-docs-site/public-publishing.md b/published-documentation/publish-a-docs-site/public-publishing.md
deleted file mode 100644
index ea8d4cf4..00000000
--- a/published-documentation/publish-a-docs-site/public-publishing.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-description: Publish your docs publicly to the web so that everyone can access them.
----
-
-# Public publishing
-
-If you created your docs for a public audience, you can publish it on the web. Spaces that you publish on the web can be [indexed by search engines](../seo.md) and will be available to anyone. If you don’t want your content to be indexed by search engines, you can disable that too — read more about that [below](public-publishing.md#publish-as-unlisted).
-
-However you publish your content, you’ll still retain control over who can _edit_ your content. And only your primary content branch will be published, so any [change requests](../../collaboration/change-requests.md) will remain private until merged.
-
-{% embed url="https://www.youtube.com/watch?v=eahJblVAZ30" %}
-
-### Publish as public
-
-To publish your docs publicly on the web head to the docs site you want to publish, click **Publish** button, and choose the **Public** option.
-
-
Publish your docs publicly
-
-### **Publish without search engine indexing**
-
-By default, your site will be indexed by search engines. You can alternatively choose to disable this — meaning the docs are still available to everyone on the web, but they _won’t_ be indexed by search engines such as Google.
-
-They will still be accessible to anyone with a the link to your documentation. Docs sites that aren’t indexed can be particularly helpful if you want to publish a beta version of your docs, or do large-scale user testing without impacting your SEO with potentially duplicate content.
-
-{% hint style="info" %}
-This feature is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
diff --git a/published-documentation/publish-a-docs-site/share-links.md b/published-documentation/publish-a-docs-site/share-links.md
deleted file mode 100644
index 4b415f52..00000000
--- a/published-documentation/publish-a-docs-site/share-links.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-description: >-
- Share links give you greater control over who can view your published GitBook
- documentation.
----
-
-# Private publishing with share links
-
-{% hint style="info" %}
-This feature is available as part of the Premium and Ultimate site plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-You can share you content privately with customers or partners without needing to invite them to your organization by using secret links.
-
-### Publish with share links
-
-To publish your docs privately, head to the [docs site’s ](../site-settings.md)settings, click **Audience settings** button, and choose the **Share links** option.
-
-
-
-Next, click on **Create link** to create a share link. You can review and name your share links, customize your domain and copy the link.
-
-Once the link is active, a private token is generated within your URL, which is unique to your space. Sharing this link will give non-GitBook users access to your content in read mode only, with an interface that looks like any other published content.
-
-You can generate as many links as you need from **Audience settings**.
-
-{% hint style="info" %}
-You can [revoked](share-links.md#revoke-a-link) and regenerate share links at any time.
-{% endhint %}
-
-### Access and permissions
-
-The content will be accessible to **anyone following the link**. Your team members can access your content from the **Docs sites** section of the sidebar, or by navigating to the space directly.
-
-### Revoke a link
-
-You can disable or regenerate your shareable by revoking it. You can see and revoke any previously generated link by opening the visibility menu and clicking through to link and domain settings.
-
-Once you revoke a link, anyone with that outdated link to your content will no longer have access.
diff --git a/published-documentation/publish-a-docs-site/visitor-authentication/README.md b/published-documentation/publish-a-docs-site/visitor-authentication/README.md
deleted file mode 100644
index fdaad21f..00000000
--- a/published-documentation/publish-a-docs-site/visitor-authentication/README.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-description: Set up custom authentication for your published content.
----
-
-# Visitor authentication
-
-{% hint style="info" %}
-This feature is available as part of the Ultimate site plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-Visitor authentication allows you to publish your content while requiring authentication from any visitors who want to view it. When enabled, GitBook lets your authentication provider handle who has access to the content.
-
-
-
-### Use cases
-
-Common use cases for visitor authentication include:
-
-* Publishing sensitive product documentation that should only be accessible to paying customers, sales prospects or partners.
-* Publishing internal knowledge base content that should only be accessible to employees of your company.
-
-### Setting up visitor authentication
-
-There are two methods you can choose from when setting up visitor authentication:
-
-1. Installing one of our authentication integrations — we currently support Okta, Azure, and Auth0. We **highly recommend** this option if you’re using an authentication provider we support.
-2. Create and host your own server to handle the authentication. Many different technologies can be used, but it’s up to you to code and maintain the solution you choose. Read the [guides in our developer documentation](https://developer.gitbook.com/visitor-authentication/guides/custom-backend) to learn more.
-
-### Publish with visitor authentication
-
-To publish your docs with visitor authentication, head to the docs site you want to publish, click **Publish**, and choose the **Visitor Authentication** option.
-
-If you’re using an external service to authenticate your users, follow the guides below to get up and running.
-
-{% embed url="https://developer.gitbook.com/visitor-authentication/guides/integrations/how-to-use-auth0-integration-for-visitor-authentication" %}
-
-{% embed url="https://developer.gitbook.com/visitor-authentication/guides/integrations/how-to-use-azure-ad-integration-for-visitor-authentication" %}
-
-{% embed url="https://developer.gitbook.com/visitor-authentication/guides/integrations/how-to-use-okta-integration-for-visitor-authentication" %}
-
-### **Publish as unlisted**
-
-By default, your site will be indexed by search engines. You can alternatively choose to publish as unlisted — meaning the docs are still available to authorized, but they _won’t_ be indexed by search engines such as Google.
-
-Unlisted spaces can be particularly helpful if you want to publish a beta version of your docs, or do large-scale user testing without impacting your SEO with potentially duplicate content.
diff --git a/published-documentation/seo.md b/published-documentation/seo.md
deleted file mode 100644
index a1728f4a..00000000
--- a/published-documentation/seo.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-icon: print-magnifying-glass
-description: Optimize your GitBook documentation to be discoverable via search engines.
----
-
-# SEO
-
-Thanks to the following features, your GitBook projects are SEO-friendly with little or no configuration on your end:
-
-
-
-Responsive design
-
-All content is suitable for mobile devices, tablets, laptops and desktops! The design for your published documentation will adapt based on the size of the device it is being viewed on.
-
-
-
-
-
-SEO-friendly content
-
-* URLs are set based on each page’s title by default, but can be customized as you wish.
-* We avoid duplicate content through smart, canonical URLs.
-* The HTML title and Open Graph title are based on the page and space title.
-* The meta description and Open Graph description are based on the page description.
-* Alt text can be added to images, which is also very important for accessibility.
-* HTML sent to crawlers is pre-rendered (i.e. server-side), meaning that crawlers do not need JavaScript to index your content.
-
-Note that we _don’t_ generate keyword meta tags, because modern search engines do not use them to rank pages. This was [officially confirmed by Google](https://developers.google.com/search/blog/2009/09/google-does-not-use-keywords-meta-tag) in 2009.
-
-
-
-
-
-Sitemap
-
-Provided that your space is published with a setting _other_ than [unlisted](../collaboration/share/share-a-space.md#unlisted-space), we automatically generate a sitemap.xml file based on your [table of contents](https://docs.gitbook.com/getting-started/overview#table-of-contents). You can locate this by going to the first page of your documentation and then appending `/sitemap.xml` to the URL. For example, the first page of our documentation is located at [docs.gitbook.com](https://docs.gitbook.com/), and so our sitemap.xml file is located at [docs.gitbook.com/sitemap.xml](https://docs.gitbook.com/sitemap.xml).
-
-
-
-
-
-Custom domain
-
-If you prefer, you can [set a custom domain](custom-domain/) for your documentation. (e.g. `docs.example.com` instead of `yourorganization.gitbook.io`)
-
-
-
-
-
-Caching & CDN
-
-All published content is cached and served via our global CDN (content delivery network). This helps to improve performance, which is an important factor within SEO.
-
-
-
-Even with these great features, it could still take some time before your documentation is indexed by Google (and other search engines). Both we and you have no _direct_ control over this, but there are two things that you could do to help improve the chance of getting your content indexed more quickly:
-
-1. Make sure that there are links to your GitBook space from other websites that have already been indexed by Google. As Google will return to re-index these sites from time to time, this increases the chance that they’ll find your space as a result of re-indexing one of these other sites.
-2. Try [submitting your site to Google](https://developers.google.com/search/docs/advanced/crawling/ask-google-to-recrawl), which essentially asks them to index it. For GitBook spaces, this will only be possible if you are using a [custom domain](custom-domain/) for your space _and_ if you create a TXT DNS record to confirm ownership of the domain.
-
-### Redirects
-
-Moving your content to GitBook or changing its structure? Broken links can impact your SEO. [Read how to set up redirects in GitBook](site-redirects.md).
-
-{% hint style="info" %}
-**Note:** Whenever you move or rename a page within GitBook, its canonical URL also changes. To keep your content accessible, GitBook automatically creates a [HTTP 301](https://en.wikipedia.org/wiki/HTTP_301) redirect from the old URL to the new one. Find out more about how automatic redirects work on [our redirects page](site-redirects.md#about-automatic-redirects).
-{% endhint %}
diff --git a/published-documentation/site-permissions.md b/published-documentation/site-permissions.md
deleted file mode 100644
index 59e32d18..00000000
--- a/published-documentation/site-permissions.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-description: Learn how to control permissions within a docs site.
-icon: lock
----
-
-# Site permissions
-
-Docs sites inherit the permissions from the **spaces** linked to them.
-
-You can view all the permissions set for users with access to the docs site from the permissions modal from the docs site’s overview page. You’ll also see which space the user’s permission was inherited from. If you’d like to change the permission, click on the space and edit the permissions on the space in the permissions modal.
-
-
-
-Users with **Administrator** or **Creator** permissions on _any_ linked space will have full access permissions on the docs site. This means that they’ll be able to control any of the publishing and customization settings.
-
-Users with **Reviewer**, **Editor**, **Commenter**, or **Reader** permissions on a linked space will be given Read-only permissions. This means they will see the docs site in the account but won't be able to access any of the settings.
diff --git a/published-documentation/site-redirects.md b/published-documentation/site-redirects.md
deleted file mode 100644
index 8801a45d..00000000
--- a/published-documentation/site-redirects.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-icon: diamond-turn-right
-description: Set up site redirects to route traffic to content anywhere on your site
----
-
-# Site redirects
-
-
Site redirects are useful when migrating documentation or restructuring content to avoid broken links, which can impact SEO.
-
-Redirects are commonly used when you are migrating your documentation from one provider to another — like when you just moved docs to GitBook. Broken links can impact SEO so we recommend setting up redirects where needed.
-
-In addition to [automatic redirects created by GitBook](site-redirects.md#about-automatic-redirects), you can create a redirect from any path in your site’s domain.
-
-## Managing redirects on your site
-
-To get started, view your site’s dashboard in GitBook and click **Settings** in the top-right corner. Scroll down to the **Redirects** section.
-
-### Creating redirects
-
-Click **Add redirect** to begin. Fill in the source path — i.e. the URL slug that you wish to redirect somewhere else — and the destination content you wish to link to. You can pick any [section](site-structure-and-navigation/site-sections.md), [variant](site-structure-and-navigation/publish-multiple-spaces-on-one-site.md), or [page](../content-editor/editor/content-structure/content-in-a-space.md) on to your site. Click **Add** to create the redirect.
-
-If you want to add another redirect to the same page, you can toggle the **Add another redirect** option on before you hit **Add**. When you add your redirect, the modal will remain open with the destination content set to the previous selection so you can add another URL slug immediately.
-
-
Clicking Add redirect opens a modal with two fields — Source path and Destination content.
-
-### Editing redirects
-
-To edit a redirect, press the **Edit** icon next to it in the list. Update the redirect and hit **Save**.
-
-To delete a redirect, press the **Delete redirect** button and confirm.
-
-
Clicking the Edit icon next to a redirect opens a modal that lets you edit or delete the redirect.
-
-## About automatic redirects
-
-Whenever pages are moved or renamed, their canonical URL changes with them. In order to keep your content accessible, GitBook automatically creates a [HTTP 301](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) redirect from the old URL to the new one.
-
-Every time a URL is loaded, GitBook resolves it through the following steps:
-
-1. Site content is resolved to its canonical URL by following any of the automatically created redirects.
-2. If the URL cannot be resolved, the URL is checked against [space-level redirects](../integrations/git-sync/content-configuration.md#redirects), defined in your repository's `.gitbook.yaml` file.
-3. Finally, the URL is checked against site-level redirects, created via [the process above](site-redirects.md#creating-redirects).
diff --git a/published-documentation/site-settings.md b/published-documentation/site-settings.md
deleted file mode 100644
index 7c93edf1..00000000
--- a/published-documentation/site-settings.md
+++ /dev/null
@@ -1,118 +0,0 @@
----
-icon: gear
-description: See which settings you can update across your published site.
----
-
-# Site settings
-
-{% hint style="info" %}
-Certain settings are only available as part of the Premium and Ultimate sites plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-Site settings allow you to customize and change certain aspects for your published site.
-
-
Site settings
-
-### Publishing
-
-
-
-Audience
-
-Choose who sees your published content. See [publish-a-docs-site](publish-a-docs-site/ "mention") for more info.
-
-
-
-
-
-Custom domain
-
-Configure a custom domain to unify your site with your own branding. See [custom-domain](custom-domain/ "mention") for more info.
-
-
-
-
-
-GitBook URL
-
-Customize the slug of your docs site (e.g. `organization.gitbook.io/custom-slug`)
-
-
-
-### Site structure
-
-{% content-ref url="site-structure-and-navigation/" %}
-[site-structure-and-navigation](site-structure-and-navigation/)
-{% endcontent-ref %}
-
-### Redirects
-
-{% content-ref url="site-redirects.md" %}
-[site-redirects.md](site-redirects.md)
-{% endcontent-ref %}
-
-### Customization
-
-
-
-Theme
-
-Align the look and feel of your docs site with your own brand. See [customization](customization/ "mention") for more info.
-
-
-
-
-
-AI search Pro & Enterprise plans
-
-Let your site visitors ask GitBook anything with AI. See [gitbook-ai.md](../content-editor/searching-your-content/gitbook-ai.md "mention") for more info.
-
-
-
-
-
-PDF export Pro & Enterprise plans
-
-Let your visitors to export your GitBook as PDF. See [pdf-export.md](../collaboration/share/pdf-export.md "mention") for more info.
-
-
-
-
-
-Page ratings Pro & Enterprise plans
-
-Choose whether or not visitors to your published content can leave a rating on each page to let you know how they feel about it. They’ll be able to choose a sad, neutral, or happy face.
-
-You can review the results of these ratings by opening the [**Insights**](insights.md) section of your docs site dashboard and selecting the [**Content scores**](insights.md#content-scores) tab.
-
-
-
-### Sharing
-
-
-
-Social preview
-
-You can upload a custom social preview image for your space. This will set the space’s `og:image` to be your uploaded image, and it’ll show when the space’s link is shared to any platform or product that supports OpenGraph images.
-
-
-
-### Danger zone
-
-
-
-Delete site
-
-Unpublish and remove your site from the **Docs site** section in the GitBook app.
-
-**Note:** Deleting a site is a permanent action and cannot be undone. Any settings and customizations will be lost, but your content will remain in its [space](../content-editor/editor/content-structure/what-is-a-space.md).
-
-
-
-
-
-Unpublish site
-
-Unpublish your site, but keep its settings and customizations. You can publish your site again at any time.
-
-
diff --git a/published-documentation/site-structure-and-navigation/README.md b/published-documentation/site-structure-and-navigation/README.md
deleted file mode 100644
index aa019ece..00000000
--- a/published-documentation/site-structure-and-navigation/README.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-icon: window-restore
-description: Decide how your site is structured to best fit your content.
----
-
-# Site structure and navigation
-
-The content on your site comes from [spaces](../../content-editor/editor/content-structure/what-is-a-space.md) in your organization. You can link one or multiple spaces. GitBook will publish each one and take care of navigation between spaces.
-
-## Content types
-
-Linked spaces can serve as one of two different content types, which determine how GitBook treats them in relation to each other and shows them to visitors.
-
-{% hint style="warning" %}
-Updated site sections are slowly rolling out to users. Hang tight, as you may not have access to this feature at this point.
-{% endhint %}
-
-
Content variants
Publish multiple versions of the same content — ideal for localization, versioning, and more.
-
-## Managing your site structure
-
-From your docs site’s dashboard, click the **Settings** button, then scroll down to **Site structure**. Here you can see all the content of your site, divided into sections and variants.
-
-Your site starts out with a single section with your site's name and a single variant with the space you linked during your [site's set-up](https://app.gitbook.com/o/d8f63b60-89ae-11e7-8574-5927d48c4877/s/NkEGS7hzeqa35sMXQZ4X/\~/changes/426/published-documentation/publish-a-docs-site).
-
-
-
-### Linking a space to your docs site
-
-To add a variant, click the **Add variant** button in the section you'd like to add to, then choose a space to link. The new variant is then added to the list of variants within the chosen section and will be available to visitors in the variant dropdown on your site.
-
-To add a section, click the **Add section** button underneath the table and choose a space to link as a section. This space will serve as the first (or only) variant within your new section. The new section is then added to the table and will be available to visitors as a tab at the top of your site.
-
-When you add a space (as a variant or section), we generate a name and slug for it based on the space's title.
-
-### Changing a linked space
-
-
-
-
-
-
-
-You can change the name and slug of each of your linked spaces by tapping the **Edit**  button in the table row of the space you'd like to edit. Edit the field(s) you'd like to change, then click the **Save** button to save.
-
-{% hint style="warning" %}
-Changing a linked space's slug will change the space's canonical URL, and might result in broken links across your site.
-{% endhint %}
-
-To replace a linked space with a different space, click on the **More menu**  in the space's table row and then click **Replace linked space**.
-
-### Reordering linked spaces
-
-Your site displays linked spaces in the order that they appear in your Site structure table. Spaces can be reordered by grabbing the **Drag handle**  and moving it up or down. Alternatively, you can press the **More menu**  in the table row of the space you'd like to edit and choosing **Move up** or **Move down**. The changed order will be reflected on your site immediately.
-
-### Setting default content
-
-If you have multiple sections in your site, one section will be marked as the default. This section is shown when visitors arrive on your site, and is served from your site's root URL. Other sections each have a slug that is appended to the root URL.
-
-If you have multiple variants within a section, one variant will be marked as the default. Like sections, the default variant is shown when visitors arrive on your site (or when they visit a section). Other variants each have a slug that is appended to the section's URL.
-
-To set a space as default, click on the **More menu**  in the space's table row and then click **Set as default**.
-
-{% hint style="info" %}
-Setting a space as default removes its slug field, as it will be served from the section root instead. We will redirect the space's slug to the appropriate path, to ensure visitors keep seeing your content.
-{% endhint %}
-
-### Remove content from a site
-
-To remove the content of a space from a site, click the **Settings** button from your docs site dashboard, then scroll down to the **Site structure** section to find the content you want to remove. Open the **More menu**  next to the linked space you want to remove and select **Delete from site**. This will remove it from the published site, but will not delete the space or the content within.
-
diff --git a/published-documentation/site-structure-and-navigation/publish-multiple-spaces-on-one-site.md b/published-documentation/site-structure-and-navigation/publish-multiple-spaces-on-one-site.md
deleted file mode 100644
index e28a98ec..00000000
--- a/published-documentation/site-structure-and-navigation/publish-multiple-spaces-on-one-site.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-icon: rectangle-history
-description: "Publish multiple versions of your documentation in a single site —\_ideal for language localization, product versions, and more."
----
-
-# Content variants
-
-You can publish multiple versions of the same documentation as part of a single docs site. These variations will be available to the end users via the space switcher in the top-left corner of the published site.
-
-{% embed url="https://www.youtube.com/watch?v=Pj7mrFArOWY" %}
-
-### Why publish multiple spaces on one site?
-
-A site with multiple spaces is useful if you need to group together the content of your spaces — such as if you’re documenting multiple versions of an API (v1, v2, v3, etc.), or documenting your content in different languages.
-
-The spaces you link can contain any content, but it is recommended to use variants as _variations of the same content_. If the spaces you link are semantically different from each other, consider adding them as [site sections](site-sections.md) instead.
-
-
Multiple spaces published through a single GitBook docs site.
-
-### Adding a variant to your docs site
-
-From your docs site’s dashboard, click the **Settings** button, then scroll down to the **Site structure** section. Here you can see all the content of your site.
-
-To add a variant, click the **Add variant** button in the section you'd like to add to, then choose a space to link. The new variant is then added to the list of variants within the chosen section and will be available to visitors in the variant dropdown on your site.
-
-
-
-### Changing a variant
-
-You can change the name and slug of each of your linked spaces by tapping the  **Edit** button in the table row of the space you'd like to edit. Edit the field(s) you'd like to change, then click the **Save** button to save.
-
-{% hint style="warning" %}
-Changing a linked space's slug will change the space's canonical URL, and might result in broken links across your site.
-{% endhint %}
-
-To replace a linked space with a different space, click on the  **More** menu in the space's table row and then click **Replace linked space**.
-
-### Reordering variants
-
-Your site displays variants in the order that they appear in your Site structure table. Variants can be reordered by grabbing the **Drag handle**  and moving it up or down. Alternatively, you can press the **More menu**  in the table row of the space you'd like to edit and choosing **Move up** or **Move down**. The changed order will be reflected on your site immediately.
-
-### Setting a default variant
-
-If you have multiple variants within a section, one variant will be marked as the default. This variant is shown when visitors arrive on your site (or when they visit a section). Other variants each have a slug that is appended to the site's URL.
-
-To set a variant as default, click on the **More menu**  in the space's table row and then click **Set as default**.
-
-{% hint style="info" %}
-Setting a space as default removes its slug field, as it will be served from the section root instead. We will redirect the space's slug to the appropriate path, to ensure visitors keep seeing your content.
-{% endhint %}
-
-### Remove a variant from a site
-
-To remove the content of a space from a site, click the **Settings** button from your docs site dashboard, then scroll down to the **Site structure** table to find the content you want to remove. Open the **More menu**  next to the linked space you want to remove and select **Delete from site**. This will remove it from the published site, but will not delete the space or the content within.
-
diff --git a/published-documentation/site-structure-and-navigation/site-sections.md b/published-documentation/site-structure-and-navigation/site-sections.md
deleted file mode 100644
index 294f3348..00000000
--- a/published-documentation/site-structure-and-navigation/site-sections.md
+++ /dev/null
@@ -1,48 +0,0 @@
----
-icon: rectangles-mixed
-description: >-
- Split your site into distinct parts — ideal for multiple products or different
- parts of your organization.
----
-
-# Site sections
-
-{% hint style="info" %}
-This feature is available as part of the Ultimate site plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-### Why split a site into multiple sections?
-
-A site with multiple sections is useful if you need to separate distinct parts of your documentation, each with its own navigation tree — such as if you're documenting different products with separate versions, or if you want to offer end-user and developer documentation separate from each other.
-
-The spaces you link as sections can contain any content, but it is recommended to use sections as _semantically different_ parts of your docs. If the spaces you'd like to link are variations of the same content, consider adding them as [content variants](publish-multiple-spaces-on-one-site.md) instead.
-
-
Multiple sections published on a single GitBook docs site.
-
-### Adding a section to your docs site
-
-From your docs site’s dashboard, click the **Settings** button, then scroll down to the **Site structure** section. Here you can see all the content of your site.
-
-To add a section, click the **Add section** button underneath the table and choose a space to link as a section. This space will serve as the first (or only) variant within your new section. The new section is then added to the table and will be available to visitors as a tab at the top of your site.
-
-
-
-### Changing a section
-
-You can change the name and slug of each of your sections by tapping the  **Edit** button in the table row of the section you'd like to edit. Edit the field(s) you'd like to change, then click the **Save** button to save.
-
-### Reordering sections
-
-Your site displays sections in the order that they appear in your Site structure table. Sections can be reordered by pressing the **More menu**  in the table row of the space you'd like to edit and choosing **Move up** or **Move down**.
-
-All the spaces within that section will be moved with it. The changed order will be reflected on your site immediately.
-
-### Setting a default section
-
-If you have multiple sections in your site, one section will be marked as the default. This section is shown when visitors arrive on your site, and is served from your site's root URL. Other sections each have a slug that is appended to the root URL.
-
-To set a section as default, click on the **More menu**  in the section's table row and then click **Set as default**.
-
-### Remove a section from a site
-
-To remove a section from a site, click the **Settings** button from your docs site dashboard, then scroll down to the **Site structure** table to find the content you want to remove. Open the **More menu**  next to the section you want to remove and select **Delete from site**. This will remove the section, along with all the variants within it, from the published site. It will not delete the space or the content within.
diff --git a/publishing-documentation/adaptive-content/README.md b/publishing-documentation/adaptive-content/README.md
new file mode 100644
index 00000000..e20f0786
--- /dev/null
+++ b/publishing-documentation/adaptive-content/README.md
@@ -0,0 +1,33 @@
+---
+description: Deliver a tailored documentation experience based on who's reading.
+icon: stars
+---
+
+# Adaptive content
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+When a user visits your site, you may already know things about them — such as who they are, which plan they’re subscribed to, and which features they have access to.
+
+Adaptive content helps to build a tailored documentation experience based on who is reading.
+
+
Personalize your user’s documentation experience through adaptive content
+
+{% hint style="info" %}
+Adaptive content is slightly different from [authenticated access](../authenticated-access/), although they can work together.
+
+While authenticated access allows you to protect your docs through a login, adaptive content customizes published material based on various authentication methods — including authenticated access or those from your own app.
+{% endhint %}
+
+### How it works
+
+Adaptive content works in one of two ways:
+
+1. Passing data from your app to GitBook
+2. Passing data from authenticated access
+
+When a user visits your sites, we call the data they bring with them their “claims” — basically data that helps to identify a user. These claims are controllable by you — the site author — and can be used through the GitBook editor to show or hide different pages, variants, and sections in your docs.
+
+Head to our page about [enabling adaptive content](enabling-adaptive-content/) to start setting up adaptive content for your site.
diff --git a/publishing-documentation/adaptive-content/adapting-your-content.md b/publishing-documentation/adaptive-content/adapting-your-content.md
new file mode 100644
index 00000000..f773f081
--- /dev/null
+++ b/publishing-documentation/adaptive-content/adapting-your-content.md
@@ -0,0 +1,96 @@
+---
+description: Tailor your content for different users.
+---
+
+# Adapting your content
+
+After setting up your authentication method, you’ll be able to use the data to adapt the content in your site for different users.
+
+You can adapt and personalize many parts of your docs, including:
+
+* Hiding or showing [pages](../../creating-content/content-structure/page.md)
+* Hiding or showing site [variants](../site-structure/variants.md)
+* Hiding or showing site [sections](../site-structure/site-sections.md)
+* Hiding or showing [header links](../customization/layout-and-structure.md#header)
+* Adding personalized content to [inline expressions](../../creating-content/variables-and-expressions.md)
+
+### Working with the condition editor
+
+The condition editor is where you’ll set the conditions for showing or hiding a page, variant, or section. After opening the condition editor, you’ll be able to write your condition as an [expression](../../creating-content/variables-and-expressions.md) that will run against data coming from visitors to your site.
+
+
+
+#### Example
+
+The data you pass through your users to GitBook is attached to an object called `visitor.claims`.
+
+Let’s take a look at an example if we want to write a conditional statement to **only show a page for users who are part of a beta program** you might define.
+
+```javascript
+visitor.claims.isBetaUser == true
+```
+
+The expression above means that any user who matches this claim (i.e. `isBetaUser` is `true` in the user’s claim), will be able to see and access the page. Any user who does not match this claim (including visitors without any claims set), will not be able to see or access the page.
+
+The condition editor also comes built in with autocomplete, which suggests claims or attributes that have been found on previous visitors to your site, helping you craft the conditional statement for your pages, variants, or sections.
+
+As you use the autocomplete, you'll notice that [variables](../../creating-content/variables-and-expressions.md#use-variables-in-your-content) are also available to use. You can combine variables that you have defined together with claims that come from user data to write conditional expressions. For example, you could:
+
+1. Set a variable for the latest version of your product
+2. Then, configure a claim that shows which version of your product is being used by a visitor to your docs
+3. Finally, write an expression to only show certain pages when a user is on the latest version of your docs
+
+You can write many different kinds of expressions , as long as they are written in valid Javascript. For instance, you can combine multiple claims into the condition editor to match specific users by using the `&&` or `||` operator. You can read more about operators [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators#binary_logical_operators).
+
+### Testing with segments
+
+Segments represent mock user data that you can configure to test your conditions.
+
+For example, you could set up a segment that represents a developer on your enterprise plan, or a sign-in user on a free plan, and then see which pages would be visible to them.
+
+[You can read more about setting up and using segments here.](testing-with-segments.md)
+
+### Conditional pages
+
+To launch the condition editor for a page, head to the actions menu next to a page, and click **Add condition.** You can also launch the condition editor from a [page’s options](../../resources/gitbook-ui.md#page-options).
+
+You can see which pages in your space have conditions set if the page has a page condition icon next to it.
+
+{% if visitor.claims.unsigned.bucket.IF_BLOCK === true %}
+### Conditional blocks
+
+To add a conditional block, begin a new line in the editor, type /, then select **Conditional content**.
+
+In the top right of the block, click on the **Condition** button to edit the condition and control the visibility of the block. Not all block types are supported within conditional blocks.
+{% endif %}
+
+### Conditional variants
+
+To launch the condition editor for a variant, head to the actions menu next to a variant, and click **Add condition**.
+
+You can see which variants in your docs have conditions set if the variant has a page condition icon next to it.
+
+### Conditional sections
+
+To launch the condition editor for a section, head to the actions menu next to a section, and click **Add condition**.
+
+You can see which sections in your docs have conditions set if the section has a page condition icon next to it.
+
+### Conditional page header links
+
+To launch the condition editor for a page header link, head to the actions menu next to a header link, and click **Add condition**.
+
+You can see which links in your docs have conditions set if the section has a page condition icon next to it.
+
+### Inline expressions
+
+In addition to controlling the visibility of content, you can also use claims inline using [expressions](../../creating-content/variables-and-expressions.md), just like page and space variables.
+
+To reference a claim inline using an expression, type / in the editor, then select **Expression**. Claims will be accessible in the expression editor as properties on `visitor` .
+
+### Working with Git Sync
+
+Conditions set in GitBook are synced through Git Sync and appear in the synced Markdown pages. This means blocks and pages with conditions set on their visibility are still visible in your synced repo.
+
+ Data passed through claims is never visible in Markdown, and is securely passed to GitBook.
+
diff --git a/publishing-documentation/adaptive-content/enabling-adaptive-content/README.md b/publishing-documentation/adaptive-content/enabling-adaptive-content/README.md
new file mode 100644
index 00000000..9a92866a
--- /dev/null
+++ b/publishing-documentation/adaptive-content/enabling-adaptive-content/README.md
@@ -0,0 +1,152 @@
+---
+description: Choose an authentication method to pass user data to GitBook.
+---
+
+# Enabling adaptive content
+
+To start customizing your documentation experience for your readers, you'll need to enable adaptive content and decide how your visitor data is passed to GitBook. This lets your site's content dynamically adapt based on who's viewing it.
+
+### Enable adaptive content
+
+Before you’re able to pass user data to GitBook, you’ll need to configure your site to use adaptive content.
+
+Head to your [site’s settings](../../site-settings.md), and enable **Adaptive content** from your site’s audience settings. Once enabled, you’ll get a generated ‘Visitor token signing key’, which you’ll need in order to continue the adaptive content setup.
+
+
Enable adaptive content
+
+### Set your visitor schema
+
+After enabling adaptive content, you’ll need to define a schema for the types of claims you expect GitBook to receive when a user visits your site.
+
+The visitor schema should reflect how these claims are structured when sent to GitBook.
+
+For example, if you expect a visitor to potentially be a beta user in your product, you would set a visitor schema similar to:
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "isBetaUser": {
+ "type": "boolean",
+ "description": "Whether the visitor is a Beta user."
+ }
+ },
+ "additionalProperties": false
+}
+```
+
+This will also help you use autocomplete when configuring your claims in the [condition editor](../adapting-your-content.md#working-with-the-condition-editor). Visitor schemas only support the following types:
+
+{% tabs %}
+{% tab title="Strings" %}
+Read claims being passed in as strings.
+
+Strings **must contain an enum** key, which needs to contain any expected values that would be found on the key being read.
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "language": {
+ "type": "string",
+ "description": "The language of the visitor",
+ "enum": [
+ "en",
+ "fr",
+ "it"
+ ]
+ },
+ "additionalProperties": false
+}
+```
+{% endtab %}
+
+{% tab title="Booleans" %}
+Read claims being passed in as booleans.
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "isBetaUser": {
+ "type": "boolean",
+ "description": "Whether the visitor is a Beta user."
+ },
+ },
+ "additionalProperties": false
+}
+```
+{% endtab %}
+
+{% tab title="Objects" %}
+Nest claims in an object to group similar values.
+
+```json
+{
+ // Top level claims
+ "type": "object",
+ "properties": {
+ // Nested claims
+ "access": {
+ "type": "object",
+ "description": "User’s access to product feature",
+ "properties": {
+ "isAlphaUser": {
+ "type": "boolean",
+ "description": "Whether the visitor is a Alpha user."
+ },
+ "isBetaUser": {
+ "type": "boolean",
+ "description": "Whether the visitor is a Beta user."
+ },
+ },
+ "additionalProperties": false
+ }
+ },
+ "additionalProperties": false
+}
+```
+{% endtab %}
+{% endtabs %}
+
+### Set an unsigned claim
+
+Unsigned claims are a specific type of claim that identifies claims coming through that might not be signed by a client application. It is required to set claims in your visitor schema as `unsigned` if you are passing claims through URL parameters, unsigned cookies, and feature flags.
+
+If you intend to work with unsigned claims, you will need to declare the claims you are expecting in the schema under an “unsigned” prop alongside your signed claims.
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "isBetaUser": {
+ "type": "boolean",
+ "description": "Whether the visitor is a Beta user."
+ },
+ // Add unsigned claims
+ "unsigned": {
+ "type": "object",
+ "description": "Unsigned claims of the site visitor.",
+ "properties": {
+ "language": {
+ "type": "string",
+ "description": "The language of the visitor",
+ "enum": [
+ "en",
+ "fr",
+ "it"
+ ]
+ }
+ },
+ "additionalProperties": false
+ }
+ },
+ "additionalProperties": false
+}
+```
+
+### Pass visitor data to GitBook
+
+GitBook provides different ways to pass visitor data to adapt your site's content. After defining your schema, you’ll need to decide how you want to pass your visitor data to GitBook.
+
+
:cookie:
Cookies
Pass visitor data into your docs through a public or signed cookie.
diff --git a/publishing-documentation/adaptive-content/enabling-adaptive-content/authenticated-access.md b/publishing-documentation/adaptive-content/enabling-adaptive-content/authenticated-access.md
new file mode 100644
index 00000000..5adcd348
--- /dev/null
+++ b/publishing-documentation/adaptive-content/enabling-adaptive-content/authenticated-access.md
@@ -0,0 +1,9 @@
+# Authenticated access
+
+GitBook offers out-of-the box solutions to protect your docs. Integrations for Auth0, Okta, Azure AD, and AWS Cognito allow you install an integration to enforce a log-in screen before being able to access your published site.
+
+Depending on which authenticated access method you’re using, you’ll still need to configure a few more things depending on which integration you’re using in order to send the right data to GitBook.
+
+Head to the relevant guide for full instructions on setting up adaptive content with authenticated access.
+
+
Setting up Auth0
Configure Auth0 with authenticated access and adaptive content.
diff --git a/publishing-documentation/adaptive-content/enabling-adaptive-content/cookies.md b/publishing-documentation/adaptive-content/enabling-adaptive-content/cookies.md
new file mode 100644
index 00000000..b8ec8dc0
--- /dev/null
+++ b/publishing-documentation/adaptive-content/enabling-adaptive-content/cookies.md
@@ -0,0 +1,126 @@
+---
+description: Pass visitor data into your docs through a public or signed cookie.
+---
+
+# Cookies
+
+{% hint style="info" %}
+Head to our guides to find a [full walk-through](https://app.gitbook.com/s/LBGJKQic7BQYBXmVSjy0/product-guides/setting-up-adaptive-content) on setting up adaptive content with cookies.
+{% endhint %}
+
+{% hint style="warning" %}
+Using adaptive content with feature flags requires adding code to your application.
+
+This method only works if your site is served under a [custom domain](../../custom-domain.md).
+{% endhint %}
+
+You can pass visitor data to your docs through your visitors browser cookies. Below is an overview of the different methods.
+
+
Method
Use-cases
Ease of setup
Security
Format
Signed cookie gitbook-visitor-token
API test credentials, customer identification
Require signing and a custom domain
✅ Properties can only be defined by the backend
JWT
Public cookie gitbook-visitor-public
Feature flags, roles
Easy to set up
❌ Visitor can override the properties
JSON
+
+### Public cookie
+
+To pass data to GitBook from a public cookie, you’ll need to send the data from your application by setting a public `gitbook-visitor-public` cookie.
+
+Below is a simple JavaScript example:
+
+```javascript
+import Cookies from 'js-cookie';
+
+const cookieData = {
+ isLoggedIn: true,
+ isBetaUser: false,
+};
+
+Cookies.set('gitbook-visitor-public', JSON.stringify(cookieData), {
+ secure: true,
+ domain: '*.acme.org',
+})
+```
+
+{% hint style="warning" %}
+Data passed through public cookies must be defined in your visitor schema through an [unsigned](https://gitbook.com/docs/publishing-documentation/adaptive-content/enabling-adaptive-content#setting-unsigned-claims) object.
+{% endhint %}
+
+### Signed cookie
+
+To pass data to GitBook more securely, you’ll need to send the data as a [JSON Web Token](https://jwt.io/introduction) from your application in a cookie named `gitbook-visitor-token` tied to your domain.
+
+To set this up, you'll need to adjust your application’s login flow to include the following steps:
+
+{% stepper %}
+{% step %}
+**Generate a JWT when users logs in to your application**
+
+Whenever a user logs in to your product, generate a JWT that contains selected attributes of your authenticated user's info.
+{% endstep %}
+
+{% step %}
+**Sign the JWT using the site's visitor signing key**
+
+Then, make sure to sign the JWT using the site's **visitor signing key**, which you can find in your site’s audience settings after enabling Adaptive Content.
+{% endstep %}
+
+{% step %}
+**Store the JWT in a wildcard session cookie**
+
+Finally you need to store the signed JWT containing your user's info into a wildcard session cookie **under your product domain**.
+
+For example, if your application is served behind the `app.acme.org` domain, the cookie will need to be created under the `.acme.org` wildcard domain.
+{% endstep %}
+{% endstepper %}
+
+Below is a simple TypeScript example:
+
+```typescript
+import * as jose from 'jose';
+
+import { Request, Response } from 'express';
+
+import { getUserInfo } from '../services/user-info-service';
+import { getFeatureFlags } from '../services/feature-flags-service';
+
+const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY;
+const GITBOOK_VISITOR_COOKIE_NAME = 'gitbook-visitor-token';
+
+
+export async function handleAppLoginRequest(req: Request, res: Response) {
+ // Your business logic for handling the login request
+ // For example, checking credentials and authenticating the user
+ //
+ // e,g:
+ // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
+
+ // After authenticating the user, retrieve user information that you wish
+ // to pass to GitBook from your database or user service.
+ const userInfo = await getUserInfo(loggedInUser.id);
+
+ // Build the JWT payload with the user's information
+ const gitbookVisitorClaims = {
+ firstName: userInfo.firstName,
+ lastName: userInfo.lastName,
+ isBetaUser: userInfo.isBetaUser
+ products: userInfo.products.map((product) => product.name),
+ featureFlags: await getFeatureFlags({userId: loggedInUser.id})
+ }
+
+ // Generate a signed JWT using the claims
+ const gitbookVisitorJWT = await new jose.SignJWT(gitbookVisitorClaims)
+ .setProtectedHeader({ alg: 'HS256' })
+ .setIssuedAt()
+ .setExpirationTime('2h') // abritary 2 hours expiration
+ .sign(GITBOOK_VISITOR_SIGNING_KEY);
+
+ // Include a `gitbook-visitor-token` cookie including the encoded JWT in your
+ // login handler response
+ res.cookie(GITBOOK_VISITOR_COOKIE_NAME, gitbookVisitorJWT, {
+ httpOnly: true,
+ secure: process.env.NODE_ENV === 'production',
+ maxAge: 2 * 60 * 60 * 1000, // abritary 2 hours expiration
+ domain: '.acme.org' //
+ });
+
+ // Rest of your login handler logic including redirecting the user to your app
+ res.redirect('/'); // Example redirect
+}
+```
diff --git a/publishing-documentation/adaptive-content/enabling-adaptive-content/feature-flags.md b/publishing-documentation/adaptive-content/enabling-adaptive-content/feature-flags.md
new file mode 100644
index 00000000..a66d79fb
--- /dev/null
+++ b/publishing-documentation/adaptive-content/enabling-adaptive-content/feature-flags.md
@@ -0,0 +1,199 @@
+---
+description: Pass visitor data into your docs through a feature flag provider.
+---
+
+# Feature flags
+
+{% hint style="warning" %}
+Using adaptive content with feature flags requires adding code to your application.
+
+Currently, the GitBook helper only supports React based setups.
+{% endhint %}
+
+GitBook provides helper functions and integrations for popular feature flag service providers like [**LaunchDarkly**](feature-flags.md#launchdarkly) and [**Reflag**](feature-flags.md#reflag).
+
+This allows you to read the feature flags users have access to in your product, as they read your docs. This is useful if you need to show documentation for features that are only available to a specific group of people.
+
+### LaunchDarkly
+
+LaunchDarkly allows you to send feature flag access as claims through the [`launchdarkly-react-client-sdk`](https://launchdarkly.com/docs/sdk/client-side/react/react-web) and GitBook’s [`@gitbook/adaptive`](https://app.gitbook.com/o/d8f63b60-89ae-11e7-8574-5927d48c4877/s/zq8ynchcecIscc4uulgN/) package.
+
+If you’re using LaunchDarkly feature flags in your product already, chances are you already have this package configured.
+
+To pass you these feature flags as claims to GitBook, follow these steps:
+
+{% stepper %}
+{% step %}
+**Install the LaunchDarkly integration**
+
+To get started, you’ll first need to [install the LaunchDarkly integration](https://app.gitbook.com/integrations/launchdarkly) into your GitBook site.
+{% endstep %}
+
+{% step %}
+**Set up your project and access keys**
+
+Add your project key and your service access token from your [LaunchDarkly settings](https://app.launchdarkly.com/settings) to the integration’s configuration.
+{% endstep %}
+
+{% step %}
+**Install and add the GitBook helper to your application**
+
+After setting up the LaunchDarkly integration, you’ll need to install the GitBook adaptive content helper in your application.
+
+```bash
+npm install @gitbook/adaptive
+```
+{% endstep %}
+
+{% step %}
+**Configure your application**
+
+You’ll need to use the `withLaunchDarkly` helper with the LaunchDarkly React SDK to pass context into GitBook.
+
+
+{% endstep %}
+
+{% step %}
+**Check your visitor schema**
+
+A [visitor schema](./#set-your-visitor-schema) is required in order for your claims to be able to be read in your published site. Installing and configuring the LaunchDarkly integration should automatically set your visitor schema for you.
+{% endstep %}
+
+{% step %}
+**Personalize your content**
+
+After setting your visitor schema, you’re ready to tailor your docs experience for the users visiting your site, using the feature flags the user has access to.
+
+Any feature flag value available in LaunchDarkly will be exposed as part of the visitor schema under the `visitor.claims.unsigned.launchdarkly` object. Read more about unsigned claims [here](./#set-an-unsigned-claim).
+
+Head to [adapting your content](../adapting-your-content.md) to learn more about personalizing your docs for your users.
+{% endstep %}
+{% endstepper %}
+
+### Reflag
+
+Reflag allows you to send feature flag access as claims through the [`@reflag/react-sdk`](https://www.npmjs.com/package/@reflag/react-sdk) and GitBook’s [`@gitbook/adaptive`](https://github.com/GitbookIO/integrations/tree/main/packages/adaptive) package.
+
+If you’re using Reflag feature flags in your product already, chances are you already have this package configured.
+
+To pass you these feature flags as claims to GitBook, follow these steps:
+
+{% stepper %}
+{% step %}
+**Install the Reflag Integration**
+
+To get started, you’ll first need to [install the Reflag integration](https://app.gitbook.com/integrations/bucket) into your GitBook site.
+{% endstep %}
+
+{% step %}
+**Set up your secret key**
+
+Add your secret key from your [Reflag settings](https://app.reflag.com/envs/current/settings/app-environments) to the integration’s configuration.
+{% endstep %}
+
+{% step %}
+**Install the GitBook helper to your application**
+
+After setting up the Reflag integration, you’ll need to install the GitBook adaptive content helper in your application.
+
+```bash
+npm install @gitbook/adaptive
+```
+{% endstep %}
+
+{% step %}
+**Configure your application**
+
+You’ll need to use the `withReflag` helper with the Reflag React SDK to pass context into GitBook.
+
+
+{% endstep %}
+
+{% step %}
+**Check your visitor schema**
+
+A [visitor schema](./#set-your-visitor-schema) is required in order for your claims to be able to be read in your published site. Installing and configuring the Reflag integration should automatically set your visitor schema for you.
+{% endstep %}
+
+{% step %}
+**Personalize your content**
+
+After setting your visitor schema, you’re ready to tailor your docs experience for the users visiting your site, using the feature flags the user has access to.
+
+Any feature flag value available in Reflag will be exposed as part of the visitor schema under the `visitor.claims.unsigned.reflag` object. Read more about unsigned claims [here](./#set-an-unsigned-claim).
+
+Head to [adapting your content](../adapting-your-content.md) to learn more about personalizing your docs for your users.
+{% endstep %}
+{% endstepper %}
+
+{% hint style="info" %}
+Feature flag values are evaluated on the client side, so avoid using this method to pass sensitive or security-critical data.
+{% endhint %}
diff --git a/publishing-documentation/adaptive-content/enabling-adaptive-content/url.md b/publishing-documentation/adaptive-content/enabling-adaptive-content/url.md
new file mode 100644
index 00000000..636dd26e
--- /dev/null
+++ b/publishing-documentation/adaptive-content/enabling-adaptive-content/url.md
@@ -0,0 +1,37 @@
+---
+description: Pass visitor data into your docs through URL query parameters.
+---
+
+# URL
+
+{% hint style="info" %}
+Head to our guides to find a [full walk-through](https://gitbook.com/docs/guides/product-guides/how-to-personalize-your-gitbook-site-using-url-parameters-and-adaptive-content) on setting up adaptive content with cookies.
+{% endhint %}
+
+You can pass visitor data to your docs through URL query parameters. Below is an overview of the method:
+
+
Method
Use-cases
Ease of setup
Security
Format
Query parameters visitor.<prop>=
Feature flags, roles
Easy to use
❌ Visitor can override the properties
JSON
+
+### Query parameters
+
+To pass data to GitBook through URL parameters, you’ll need to pass the data in the URL in the format `visitor.`.
+
+For example:
+
+```url
+https://docs.acme.org/?visitor.language=fr
+```
+
+This will allow you to use these claims in the [condition editor](../adapting-your-content.md#working-with-the-condition-editor) under the unsigned object:
+
+```javascript
+visitor.claims.unsigned.language === "fr"
+```
+
+{% hint style="warning" %}
+Data passed through query parameters must be defined in your visitor schema through an [unsigned](https://gitbook.com/docs/publishing-documentation/adaptive-content/enabling-adaptive-content#setting-unsigned-claims) object. Additionally, query parameters can be easily changed by the visitor and are best suited for non-sensitive information.
+{% endhint %}
+
+### Video tutorial
+
+{% embed url="https://www.youtube.com/embed/hCd2_AAHU_I?si=jm2VOThMVh7NdJm_" %}
diff --git a/publishing-documentation/adaptive-content/testing-with-segments.md b/publishing-documentation/adaptive-content/testing-with-segments.md
new file mode 100644
index 00000000..56abdb1c
--- /dev/null
+++ b/publishing-documentation/adaptive-content/testing-with-segments.md
@@ -0,0 +1,43 @@
+---
+description: Test your conditions with mock data.
+---
+
+# Testing with segments
+
+Segments allow you to test the conditions you set by defining claims on a mock user.
+
+For example, you might want to only show a page or section to beta users. By creating a segment and defining the properties associated with this group of mock users, you can mimic a segment that is specific to the users you’re targeting.
+
+
The segment editor in GitBook.
+
+### Create a segment
+
+To create a new segment, head to the condition editor, and click the settings icon next to an existing segment in the segment dropdown.
+
+Here you’ll be able to define the data that will appear on a mock user. Because this is the data that’s being represented, the `visitor.claims` key is omitted.
+
+#### Example
+
+To create a segment for beta users following the examples in our docs, you would create a new segment, and add the following data.
+
+```json
+{
+ "isBetaUser": true
+}
+```
+
+When heading back to the condition editor, selecting the beta segment we created should show that the page we’re viewing **would** be accessible to our test user.
+
+
Testing a segment in GitBook.
+
+### Detected segments
+
+Detected segments allow you to get a sense of the type of claims you are receiving from visitors to your site.
+
+These segments are not editable, but allow you to copy/paste claims from the segment editor to create your own user segments.
+
+### Testing segments in the preview
+
+In addition to testing segments in the segment editor, you’ll be able to use your segments in real time in the preview when viewing changes for your site.
+
+Use the dropdown in the upper left corner when in preview mode for your site to choose a segment to see how your site will look for your chosen segment.
diff --git a/publishing-documentation/authenticated-access/README.md b/publishing-documentation/authenticated-access/README.md
new file mode 100644
index 00000000..b7bb4fc6
--- /dev/null
+++ b/publishing-documentation/authenticated-access/README.md
@@ -0,0 +1,28 @@
+---
+description: Set up custom authentication for your published content
+icon: key
+---
+
+# Authenticated access
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+Authenticated access allows you to publish your content while requiring authentication from any visitors who want to view it. When enabled, GitBook lets your authentication provider handle who has access to the content.
+
+
Add a sign in to your published documentation.
+
+### Use cases
+
+Common use cases for authenticated access include:
+
+* Publishing sensitive product documentation that should only be accessible to paying customers, sales prospects or partners.
+* Publishing internal knowledge base content that should only be accessible to employees of your company.
+
+### How it works
+
+There are two methods you can choose from when setting up authenticated access:
+
+1. Installing one of our authentication integrations — we currently support Okta, Azure, and Auth0. We **highly recommend** this option if you’re using an authentication provider we support.
+2. Create and host your own server to handle the authentication. Many different technologies can be used, but it’s up to you to code and maintain the solution you choose.
+
+Head to [Enabling authenticated access](enabling-authenticated-access.md) to start setting up protected access for your site.
diff --git a/publishing-documentation/authenticated-access/enabling-authenticated-access.md b/publishing-documentation/authenticated-access/enabling-authenticated-access.md
new file mode 100644
index 00000000..68aa2f78
--- /dev/null
+++ b/publishing-documentation/authenticated-access/enabling-authenticated-access.md
@@ -0,0 +1,15 @@
+# Enabling authenticated access
+
+To protect your docs behind a sign-in screen, you’ll need to first enable authenticated access for your site.
+
+### Enable authenticated access
+
+Head to your [site’s settings](../site-settings.md), and choose **Authenticated access** from your site’s audience settings. Once selected, you’ll see a few options you’ll need to continue configuring your site. You’ll also see a generated "**Private key**", which you’ll need at a later point in the authenticated access setup.
+
+### Choose an authentication method
+
+Depending on your setup, we have integrations and guides on setting up authenticated access for different tools.
+
+Head to the relevant guide to continue setting up authenticated access for your site.
+
+
diff --git a/publishing-documentation/authenticated-access/setting-up-a-custom-backend.md b/publishing-documentation/authenticated-access/setting-up-a-custom-backend.md
new file mode 100644
index 00000000..94b1d10c
--- /dev/null
+++ b/publishing-documentation/authenticated-access/setting-up-a-custom-backend.md
@@ -0,0 +1,238 @@
+---
+description: Set up a custom login screen for visitors to your docs.
+---
+
+# Setting up a custom backend
+
+{% hint style="warning" %}
+This guide takes you through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through the process of [enabling authenticated access](enabling-authenticated-access.md).
+{% endhint %}
+
+This guide walks you through setting up a protected sign-in screen for your GitBook documentation site using your own **custom** authentication backend.
+
+{% hint style="info" %}
+If you are using one of the authentication providers we support or have an [OpenID Connect](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol) (OIDC) compliant backend, check out our integration guides for a more streamlined setup:\
+\
+[Auth0](setting-up-auth0.md) | [Azure AD](setting-up-azure-ad.md) | [Okta](setting-up-okta.md) | [AWS Cognito](setting-up-aws-cognito.md) | [OIDC](setting-up-oidc.md)
+{% endhint %}
+
+### Overview
+
+To setup a custom authentication system for your GitBook site, follow these key steps:
+
+{% stepper %}
+{% step %}
+[**Create a custom backend to authenticate your users**](setting-up-a-custom-backend.md#id-1.-create-a-custom-backend-to-authenticate-your-users)
+
+Implement a backend that prompts users to login and authenticate them.
+{% endstep %}
+
+{% step %}
+[**Sign and pass a JWT token to GitBook**](setting-up-a-custom-backend.md#id-2.-sign-and-pass-a-jwt-token-to-gitbook)
+
+Create a JWT token and sign it with your site’s private key.
+{% endstep %}
+
+{% step %}
+[**Configure a fallback URL**](setting-up-a-custom-backend.md#id-3.-configure-a-fallback-url)
+
+Configure a URL to be used when an unauthenticated visitor access your site.
+{% endstep %}
+
+{% step %}
+[**Set up multi-tenant authenticated access (optional)**](setting-up-a-custom-backend.md#id-4.-set-up-multi-tenant-authenticated-access)
+
+Configure your backend to handle authentication across multiple GitBook sites.
+{% endstep %}
+
+{% step %}
+[**Configure your backend for adaptive content (optional)**](setting-up-a-custom-backend.md#id-5.-configure-your-backend-for-adaptive-content)
+
+Configure your backend to work with adaptive content in GitBook.
+{% endstep %}
+{% endstepper %}
+
+### 1. Create a custom backend to authenticate your users
+
+In order to start authenticating users before they can visit your documentation, you’ll need to set up a server that can handle login and authentication of users.
+
+Your backend should:
+
+* Prompt users to log in using your preferred authentication method.
+* Validate user credentials and authenticate them.
+* Generate and sign a **JSON Web Token (JWT)** upon successful authentication.
+* Redirect users to GitBook with the JWT included in the URL.
+
+### 2. Sign and pass a JWT token to GitBook
+
+Once your backend authenticates a user, it must **generate a JWT** and **pass it to GitBook** when **redirecting** them to your site. The token should be signed using the **private key** provided in your site's audience settings after [enabling authenticated access](enabling-authenticated-access.md#enable-authenticated-access).
+
+The following example should demonstrate how a login request handler in your custom backend could look like:
+
+{% code title="index.ts" %}
+```typescript
+import { Request, Response } from 'express';
+import * as jose from 'jose';
+
+import { getUserInfo } from '../services/user-info-service';
+import { getFeatureFlags } from '../services/feature-flags-service';
+
+const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY!;
+const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/myspace';
+
+export async function handleAppLoginRequest(req: Request, res: Response) {
+ // Your business logic for handling the login request
+ // For example, checking credentials and authenticating the user
+ //
+ // e.g.:
+ // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
+
+ // Generate a signed JWT
+ const gitbookVisitorJWT = await new jose.SignJWT({})
+ .setProtectedHeader({ alg: 'HS256' })
+ .setIssuedAt()
+ .setExpirationTime('2h') // Arbitrary 2-hour expiration
+ .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
+
+ // Redirect the user to GitBook with the JWT token in the URL
+ const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
+ res.redirect(redirectURL);
+}
+```
+{% endcode %}
+
+### 3. Configure a fallback URL
+
+The fallback URL is used when an unauthenticated visitor tries to access your protected site. GitBook will then redirect them to this URL.
+
+This URL should point to a handler in your custom backend, where you can prompt them to login, authenticate and then redirect them back to your site with the JWT included in the URL.
+
+For instance, if your login screen is located at `https://example.com/login`, you should include this value as the fallback URL.
+
+You can configure this fallback URL within your site’s audience settings under the "Authenticated access" tab.
+
+
Configure a fallback URL
+
+When redirecting to the fallback URL, GitBook includes a `location` query parameter to the fallback URL that you can leverage in your handler to redirect the user to the original location of the user:
+
+```javascript
+const gitbookVisitorJWT = await new jose.SignJWT({})
+ .setProtectedHeader({ alg: 'HS256' })
+ .setIssuedAt()
+ .setExpirationTime('2h') // Arbitrary 2-hour expiration
+ .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
+
+// Redirect to the original GitBook docs URL with the JWT included as jwt_token query parameter
+// If a location is provided, the user will be redirected back to their original destination
+const redirectURL = `${GITBOOK_DOCS_URL}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
+res.redirect(redirectURL);
+```
+
+{% hint style="warning" %}
+Because GitBook relies on the `location` search param - you cannot use it in your fallback URL. For example, `https://auth.gitbook.com/?location=something` is not a valid fallback URL.
+{% endhint %}
+
+### 4. Set up multi-tenant authenticated access (optional)
+
+If you’re using GitBook as a platform to provide content to your different customers, you probably need to set up multi-tenant authenticated access. Your authentication backend needs to be responsible for handling authentication across multiple different sites. This is possible in GitBook with a few small tweaks to your custom authentication backend code.
+
+#### Adding all tenants to your authentication server
+
+Your authentication backend will need to know the JWT signing keys and the URLs of all the GitBook sites you expect it to handle. If you have two sites in your organization for Customer A and Customer B, you can imagine your authentication code storing such mapping:
+
+```typescript
+const CUSTOMER_A = {
+ jwtSigningKey: 'aaa-aaa-aaa-aaa',
+ url: 'https://mycompany.gitbook.io/customer-a'
+};
+
+const CUSTOMER_B = {
+ jwtSigningKey: 'bbb-bbb-bbb-bbb',
+ url: 'https://mycompany.gitbook.io/customer-b'
+};
+```
+
+#### Giving your authentication server additional context
+
+When GitBook is unable to authenticate a user's request, it redirects them to the fallback URL. This URL points to your authentication backend, which is responsible for authenticating the user and redirecting them back to the requested content.
+
+To support multiple tenants, your authentication backend needs to know which GitBook site the user is meant to access. This information can be passed in the fallback URL.
+
+So for example, you could setup the fallback URLs for each sites as follow:
+
+
+
+Your authentication backend can then check this information and handle the redirection to the correct site accordingly:
+
+```javascript
+const customerInfo = req.query.site === 'customer-a' ? CUSTOMER_A : CUSTOMER_B;
+
+const gitbookVisitorJWT = await new jose.SignJWT({})
+ .setProtectedHeader({ alg: 'HS256' })
+ .setIssuedAt()
+ .setExpirationTime('2h') // Arbitrary 2-hour expiration
+ .sign(new TextEncoder().encode(customerInfo.jwtSigningKey));
+
+// Redirect to the original GitBook docs URL with the JWT included as jwt_token query parameter
+// If a location is provided, the user will be redirected back to their original destination
+const redirectURL = `${customerInfo.url}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
+res.redirect(redirectURL);
+```
+
+### 5. Configure your backend for adaptive content (optional)
+
+{% include "../../.gitbook/includes/adaptive-content-development-hint.md" %}
+
+To leverage the Adaptive Content capability in your authenticated access setup, you can include additional user attributes (claims) in the payload of the JWT that your custom backend generates and include in the URL when redirecting the user to the site.
+
+These claims when included in the JWT are used by GitBook to [adapt content](../adaptive-content/adapting-your-content.md) dynamically for your site visitors.
+
+Putting it all together, the following code example demonstrates how you could include these claims in the JWT, which can then be used by GitBook to adapt content for your visitors:
+
+{% code title="index.ts" %}
+```typescript
+import { Request, Response } from 'express';
+import * as jose from 'jose';
+
+import { getUserInfo } from '../services/user-info-service';
+import { getFeatureFlags } from '../services/feature-flags-service';
+
+const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY!;
+const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/myspace';
+
+export async function handleAppLoginRequest(req: Request, res: Response) {
+ // Your business logic for handling the login request
+ // For example, checking credentials and authenticating the user
+ //
+ // e.g.:
+ // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
+
+ // For the purpose of this example, assume a logged-in user object
+ const loggedInUser = { id: '12345' }; // Replace with actual authentication logic
+
+ // Retrieve user information to pass to GitBook
+ const userInfo = await getUserInfo(loggedInUser.id);
+
+ // Generate a signed JWT and include the user attributes as claims
+ const gitbookVisitorClaims = {
+ firstName: userInfo.firstName,
+ lastName: userInfo.lastName,
+ isBetaUser: userInfo.isBetaUser,
+ products: userInfo.products.map((product) => product.name),
+ featureFlags: await getFeatureFlags({ userId: loggedInUser.id })
+ };
+
+ const gitbookVisitorJWT = await new jose.SignJWT(gitbookVisitorClaims)
+ .setProtectedHeader({ alg: 'HS256' })
+ .setIssuedAt()
+ .setExpirationTime('2h') // Arbitrary 2-hour expiration
+ .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
+
+ // Redirect the user to GitBook with the JWT token in the URL
+ const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
+ res.redirect(redirectURL);
+}
+```
+{% endcode %}
+
+After setting up and configuring the right claims to send to GitBook, head to “[Adapting your content](../adaptive-content/adapting-your-content.md)” to continue configuring your site.
diff --git a/publishing-documentation/authenticated-access/setting-up-auth0.md b/publishing-documentation/authenticated-access/setting-up-auth0.md
new file mode 100644
index 00000000..041aa59c
--- /dev/null
+++ b/publishing-documentation/authenticated-access/setting-up-auth0.md
@@ -0,0 +1,103 @@
+---
+description: Set up an Auth0 login screen for visitors to your docs.
+---
+
+# Setting up Auth0
+
+{% hint style="info" %}
+Head to our guides to find a [full walk-through](https://gitbook.com/docs/guides/product-guides/how-to-personalize-your-gitbook-site-using-auth0-and-adaptive-content) on setting up authenticated access and adaptive content with Auth0.
+{% endhint %}
+
+{% hint style="warning" %}
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through [Enabling authenticated access](enabling-authenticated-access.md).
+{% endhint %}
+
+To setup your GitBook site with authenticated access using Auth0, the process looks as follows:
+
+{% stepper %}
+{% step %}
+#### [Create a new application in Auth0](setting-up-auth0.md#id-1.-create-a-new-application-in-auth0)
+
+Create an Auth0 application in your Auth0 dashboard.
+{% endstep %}
+
+{% step %}
+#### [Install and configure the Auth0 integration](setting-up-auth0.md#id-2.-install-and-configure-the-auth0-integration)
+
+Install the Auth0 integration and add the required configuration to your GitBook site.
+{% endstep %}
+
+{% step %}
+#### [Configure Auth0 for Adaptive content (optional)](setting-up-auth0.md#id-3.-configure-auth0-for-adaptive-content-optional)
+
+Configure Auth0 to work with adaptive content in GitBook.
+{% endstep %}
+{% endstepper %}
+
+### 1. Create a new application in Auth0
+
+Start by creating a new application in your Auth0 platform dashboard. This application will allow the GitBook Auth0 integration to request tokens to validate user identity before granting them access to your site.
+
+1. Sign in to your Auth0 [dashboard](https://manage.auth0.com/dashboard/).
+2. Head to **Applications > Applications** section from the left sidebar.
+3. Click on the **+ Create Application** button, and give your app a name.
+4. Under the **Choose an application type,** select **Regular Web Applications**.
+5. In the **Quickstart** screen of the newly created app, select **Node.js (Express)** and then **I want to integrated my app**.
+6. You should then see a configuration screen like below.\
+ Click **Save Settings And Continue**.\
+
+
+
+7. Click on the **Settings** tab.
+8. Copy and make note of the **Domain**, **Client ID** and **Client Secret**.
+
+{% hint style="warning" %}
+Please ensure that you have **at least one connection enabled** for your Auth0 application under the **Connections** tab.
+{% endhint %}
+
+### 2. Install and configure the Auth0 integration
+
+Once you've created the Auth0 application, the next step is to install the Auth0 integration in GitBook and link it with your Auth0 application using the credentials you generated earlier:
+
+1. Navigate to the site where you've enabled authenticated access and want to use Auth0 as the identity provider.
+2. Click on the **Integrations** button in the top right from your site’s settings.\
+
+
+
+3. Click on **Authenticated Access** from the categories in the sidebar.
+4. Select the **Auth0** integration.
+5. Click **Install on this site**.\
+
+
+
+6. After installing the integration on your site, you should see the integration's configuration screen:\
+
+
+
+7. Enter the **Domain**, **Client ID** and **Client Secret** values you copied after creating the Auth0 application earlier. For Auth0 Domain, enter the Domain copied from Auth0 (make sure to prefix it with `https://`).
+8. **(optional)** Enable the **Include claims in JWT token** option at the bottom of the dialog if you have enabled your site for [adaptive content](../adaptive-content/enabling-adaptive-content/).
+9. Copy and make note of the **Callback** **URL** displayed **at the bottom of the dialog**.
+10. Click **Save**.
+11. Head back to the Auth0 application you created earlier in the Auth0 dashboard.
+12. Browse to **Applications > Applications** in the sidebar and select the **Settings** tab.
+13. Scroll down to the **Application URIs** section of the settings
+14. Paste the **Callback URL** you copied earlier from the GitBook integration dialog into the **Allowed Callback URL** input field.
+15. Click **Save.**
+16. Head back to **Auth0 integration** installation screen **in GitBook**.
+17. Close the integration dialogs and click on the **Settings** tab in the site screen.
+18. Browse to **Audience** and select **Authenticated access** (if not already selected).
+19. Select **Auth0** from the dropdown in the **Authentication backend** section.
+20. Click **Update audience**.
+21. Head to the site's overview screen and click **Publish** if the site is not already published.
+
+Your site is now published behind authenticated access using your Auth0 as identity provider.
+
+To test it out, click on **Visit**. You will be asked to sign in with Auth0, which confirms that your site is published behind authenticated access using Auth0.
+
+### 3. Configure Auth0 for Adaptive content (optional)
+
+{% embed url="https://www.youtube.com/embed/uhWeQkgyg8Y?si=7_kD3RF-Is_MnYhZ" %}
+
+To leverage the Adaptive Content capability in your authenticated access site, [configure the Auth0 application](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims) to include additional user information in the authentication token as claims.
+
+These claims, represented as key-value pairs, are passed to GitBook and can be used to [adapt content](../adaptive-content/adapting-your-content.md) dynamically for your site visitors.
diff --git a/publishing-documentation/authenticated-access/setting-up-aws-cognito.md b/publishing-documentation/authenticated-access/setting-up-aws-cognito.md
new file mode 100644
index 00000000..d897d717
--- /dev/null
+++ b/publishing-documentation/authenticated-access/setting-up-aws-cognito.md
@@ -0,0 +1,102 @@
+---
+description: Set up an AWS Cognito login screen for visitors to your docs.
+---
+
+# Setting up AWS Cognito
+
+{% hint style="warning" %}
+This guide takes you through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through the process of [enabling authenticated access](enabling-authenticated-access.md).
+{% endhint %}
+
+To setup your GitBook site with authenticated access using AWS Cognito, the process looks as follows:
+
+{% stepper %}
+{% step %}
+#### Create a new AWS Cognito application
+
+Create an AWS Cognito application from your AWS dashboard.
+{% endstep %}
+
+{% step %}
+#### Install and configure the AWS Cognito integration
+
+Install the AWS Cognito integration and add the required configuration.
+{% endstep %}
+
+{% step %}
+#### Configure AWS Cognito for adaptive content (optional)
+
+Configure AWS Cognito to work with adaptive content in GitBook.
+{% endstep %}
+{% endstepper %}
+
+### Create a new AWS Cognito application
+
+Go to your desired User Pool in Cognito, and click on App integration. Make a note of the Cognito domain, we will need it to configure the integration.
+
+Scroll to the bottom and click "Create app client". For the app type, select "Confidential client." Scroll down to Hosted UI settings. In allowed Callback URLs, enter the Callback URL you got from GitBook upon installing the integration on a space.
+
+Scroll further down to "OAuth 2.0 grant types"- make sure "Authorization code grant" is selected.
+
+For "OpenID connect scopes", make sure OpenID is selected.
+
+Scroll down and click "Create app client".
+
+Click on the created app client and make a note of the Client ID and Client Secret.
+
+### Install and configure the AWS Cognito integration
+
+Navigate to integrations within the GitBook app, select authenticated access as the category, and install the AWS Cognito integration.
+
+
+
+Once you've installed it on your site, go to configuration and make a note of the Callback URL right above the Save button. We will need it to set up Cognito.
+
+Open up the Cognito integration's configuration screen for the space you installed the integration on.
+
+It should look like the following image:
+
+
+
+For Client ID, Cognito Domain, and Client Secret, paste in the values you got from Cognito.
+
+Hit Save.
+
+Now, in GitBook, close the integrations modal and click on the Manage site button. Navigate to **Audience**, select **Authenticated access**, and choose Cognito as the backend. Then, click **Update audience**. Go to the site’s screen and click **Publish**.\
+\
+The site is now published behind authenticated access controlled by your Auth0 application. To try it out, click on Visit. You will be asked to sign in with Cognito, which confirms that your site is published behind authenticated access using Auth0.
+
+### Configure AWS Cognito for adaptive content (optional)
+
+To leverage Adaptive Content with authenticated access in GitBook, you’ll need to configure your Amazon Cognito user pool to include custom claims in the ID token.
+
+This is typically done by creating a [Cognito Lambda trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html)—specifically a _Pre Token Generation_ Lambda—that returns a JSON payload overriding or appending custom claims. These claims might include user roles, subscription tiers, or any other metadata relevant to your content.
+
+Here’s an example of what that could look like:
+
+```javascript
+export const handler = async (event, context) => {
+ // Retrieve user attribute from event request
+ const userAttributes = event.request.userAttributes;
+
+ // Add additional claims to event response
+ event.response = {
+ "claimsAndScopeOverrideDetails": {
+ "idTokenGeneration": {},
+ "accessTokenGeneration": {
+ "claimsToAddOrOverride": {
+ "products": ['api', 'sites', 'askAI'],
+ "isBetaUser": true,
+ "isAlphaUser": true,
+ }
+ }
+ }
+ };
+ // Return to Amazon Cognito
+ context.done(null, event);
+};
+```
+
+
+
+Once added, these key-value pairs are included in the authentication token and passed to GitBook, allowing your site to dynamically adapt its content based on the authenticated user’s profile.
diff --git a/publishing-documentation/authenticated-access/setting-up-azure-ad.md b/publishing-documentation/authenticated-access/setting-up-azure-ad.md
new file mode 100644
index 00000000..406ba5cf
--- /dev/null
+++ b/publishing-documentation/authenticated-access/setting-up-azure-ad.md
@@ -0,0 +1,138 @@
+---
+description: Set up an Azure AD login screen for visitors to your docs.
+---
+
+# Setting up Azure AD
+
+{% hint style="warning" %}
+This guide takes you through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through the process of [enabling authenticated access](enabling-authenticated-access.md).
+{% endhint %}
+
+{% hint style="info" %}
+There is a known limitation with the Azure integration where heading URL fragments will be removed upon authentication. The user will still land on the correct page, but will be taken to the top of the page instead of the heading in the URL. Once a user is authenticated this behavior will no longer occur during a session and the user would be directed to the correct heading.
+
+This is due to a security measure put in place by Microsoft.
+{% endhint %}
+
+### Overview
+
+To setup your GitBook site with authenticated access using Azure AD, the process looks as follows:
+
+{% stepper %}
+{% step %}
+#### [Create an app registration in Azure AD](setting-up-azure-ad.md#id-1.-create-an-app-registration-in-azure-a-d)
+
+Create an Azure AD application registration in your Microsoft Entra ID admin dashboard.
+{% endstep %}
+
+{% step %}
+#### [Install and configure the Azure AD integration on your site](setting-up-azure-ad.md#id-2.-install-and-configure-the-azure-a-d-integration)
+
+Install the Azure AD integration and add the required configuration to your GitBook site.
+{% endstep %}
+
+{% step %}
+#### [Configure Azure AD for adaptive content (optional)](setting-up-azure-ad.md#id-3.-configure-azure-a-d-for-adaptive-content-optional)
+
+Configure your Azure AD to work with Adaptive content in GitBook.
+{% endstep %}
+{% endstepper %}
+
+### 1. Create an app registration in Azure AD
+
+Start by creating an app registration in your Microsoft Entra ID dashboard. This application registration will allow the GitBook Azure AD integration to request tokens to validate user identity before granting them access to your site.
+
+1. Sign in to your Microsoft Entra ID admin [dashboard](https://entra.microsoft.com/).
+2. Head to **Identity** > **Applications** > **App registrations** from the left sidebar.
+3. Click on **+ New registration,** and give your registration a name.
+4. Under **Supported account types,** select “**Accounts in this organizational directory only (Default Directory only - Single tenant)”**.
+5. Leave the Redirect URI field empty for now—you will need to fill this in later.
+6. Click **Register** to complete the app registration.\
+
+
+
Register an app for the GitBook VA integration.
+7. You should then see your new app registration **Overview** screen. Copy and make note of the **Application (client) ID** and **Directory (tenant) ID**.\
+
+
+
Overview of the newly created app registration.
+8. Click on **Add a certificate or secret**. You should see the following **Certificates & Secrets** screen:\
+
+
+
Add a certificate or secret.
+9. Click on **+ New client secret**.
+10. Enter suitable description for the secret and click **Add**.
+11. Copy and make note of the **Value** field (_**not** the Secret ID_) of the secret you just created.
+
+### 2. Install and configure the Azure AD integration
+
+Once you've created the Azure AD app registration, the next step is to install the Azure AD integration in GitBook and link it with your Azure application using the credentials you generated earlier:
+
+1. Navigate to the site where you’ve [enabled authenticated access](enabling-authenticated-access.md#enable-authenticated-access) and want to use Azure AD as the identity provider.
+2. Click on the **Integrations** button in the top right from your site’s settings.\
+
+
+
+3. Click on **Authenticated Access** from the categories in the sidebar.
+4. Select the **Azure** integration.
+5. Click **Install on this site**.\
+
+
+
+6. After installing the integration on your site, you should see the integration's configuration screen:\
+
+
+
+7. Enter the **Client ID**, **Tenant ID**, and **Client Secret** values you copied after [creating the Azure AD app registration](setting-up-azure-ad.md#id-1.-create-an-app-registration-in-azure-a-d) earlier, and click “Save”.
+8. Copy the **URL** displayed **at the bottom of the dialog**.
+9. Head back to the Azure AD app registration you created earlier in the Microsoft Entra ID dashboard.
+10. Browse to **Manage** > **Authentication** in the sidebar.
+11. Click **+ Add a platform** and select **Web** card in the panel that opens.\
+
+
+
+12. Paste the GitBook integration **URL** you copied earlier in the **Redirect URI** field, and click “Configure”\
+
+
+
+13. Head back to **Azure integration** installation screen **in GitBook**.
+14. Close the integration dialogs and click on the **Settings** tab in the site screen.
+15. Browse to **Audience** and select **Authenticated access** (if not already selected).
+16. Select **Azure** from the dropdown in the **Authentication backend** section.
+17. Click **Update audience**.\
+
+
+
+18. Head to the site's overview screen and click **Publish** if the site is not already published.
+
+Your site is now published behind authenticated access using your Azure AD as identity provider.
+
+To test it out, click on Visit. You will be asked to sign in with Azure, which confirms that your site is published behind authenticated access using Azure.
+
+{% hint style="info" %}
+Upon accessing the published content URL and after logging in with your Azure credentials, you may see a screen telling you that you need to "Request approval" from your admin. Your admin can grant this request by accessing the published content URL, logging in, and granting approval on behalf of the organization.
+{% endhint %}
+
+### 3. Configure Azure AD for Adaptive content (optional)
+
+To leverage the Adaptive Content capability in your authenticated access site, configure the Azure AD app registration to include additional user information in the authentication token as claims.
+
+These claims, represented as key-value pairs, are passed to GitBook and can be used to [adapt content](../adaptive-content/adapting-your-content.md) dynamically for your site visitors.
+
+Azure AD supports different types and levels of claims, each with its own method of setup:
+
+* **Standard Claims**: Common claims that may be included in tokens but are not always present by default.
+
+{% hint style="info" %}
+Azure AD keeps token sizes optimized for performance. As a result, many claims are **not** included in the token by default and must be explicitly requested by the application. To ensure claims like `email` , `groups` or `roles` are included, they must be explicitly requested as **optional claims**.
+{% endhint %}
+
+* **Optional Claims**: Additional predefined claims that can be enabled for an application.
+* **Custom Claims**: Claims sourced from custom user attributes in Azure AD or external systems via a custom claims provider.
+
+For more details on how to include these different types of claims in the tokens generated by your Azure AD app, refer to the following Microsoft Entra documentation guides:
+
+* [User Attributes](https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-add-attributes-to-token)
+* [Optional Claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?toc=%2Fentra%2Fexternal-id%2Ftoc.json\&bc=%2Fentra%2Fexternal-id%2Fbreadcrumb%2Ftoc.json\&tabs=appui)
+* [Custom Claims](https://learn.microsoft.com/en-us/entra/identity-platform/custom-claims-provider-overview)
+
+After setting up and configuring the right claims to send to GitBook, head to “[Adapting your content](../adaptive-content/adapting-your-content.md)” to continue configuring your site.
diff --git a/publishing-documentation/authenticated-access/setting-up-oidc.md b/publishing-documentation/authenticated-access/setting-up-oidc.md
new file mode 100644
index 00000000..a1794c0e
--- /dev/null
+++ b/publishing-documentation/authenticated-access/setting-up-oidc.md
@@ -0,0 +1,77 @@
+---
+description: Set up an OIDC login screen for visitors to your docs.
+---
+
+# Setting up OIDC
+
+{% hint style="warning" %}
+This guide takes you through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through the process of [enabling authenticated access](enabling-authenticated-access.md).
+{% endhint %}
+
+To setup your GitBook site with authenticated access using OIDC, the process looks as follows:
+
+{% stepper %}
+{% step %}
+#### Create a new application with your identity provider
+
+Create an application from your identity provider’s dashboard.
+{% endstep %}
+
+{% step %}
+#### Install and configure the OIDC integration
+
+Install the Auth0 integration and add the required configuration.
+{% endstep %}
+{% endstepper %}
+
+OIDC stands for OpenID Connect, and it's an identity layer built on top of OAuth. Many identity providers abide by OIDC, and GitBook's OIDC integration for authenticated access allows you to publish your space behind authenticated access, and access to the content is controlled by your Identity Provider
+
+{% hint style="info" %}
+Since this guide is a generic guide meant for all identity providers, some details may vary depending on your Identity Provider. For illustration purposes, we are using Google as the identity provider in this guide.
+{% endhint %}
+
+### Create a new application with your identity provider
+
+There are some things that you need to set up on your Identity Provider in order to get the integration to work.
+
+You need to create a new app inside your Identity Provider. Its type should be "Web Application." In Google, you create these under "API and Services", "Credentials", and then under "OAuth 2.0 Client IDs."\\
+
+
+
+Click on Create Credentials, select OAuth Client ID, select Web Application as the type, name it appropriately, and under Authorized Redirect URIs, enter the Callback URL you got from GitBook.
+
+Click Create. Make a note of the Client ID and Client Secret. We will need these to finish configuring of our integration in GitBook.
+
+### Install and configure the OIDC integration
+
+Navigate to integrations within the GitBook app, select authenticated access as the category, and install the OIDC integration. Install the OIDC integration on your chosen docs site.
+
+
+
+Once you've installed it on your site, go to configuration and make a note of the Callback URL right above the Save button. We may need it to set up the Identity Provider.
+
+Open up the OIDC integration's configuration screen for the space you installed the integration on.
+
+It should look like the following image
+
+
+
+For Client ID and Client Secret, paste in the values you got for your identity provider.
+
+Now, you will need to find the Authorization Endpoint and Access Token Endpoint for your Identity Provider. For Google, these are `https://accounts.google.com/o/oauth2/v2/auth` and `https://oauth2.googleapis.com/token` respectively.
+
+{% hint style="info" %}
+If you are not using Google, these endpoints will be different for you. Please look into the documentation of your identity provider to locate these endpoints
+{% endhint %}
+
+For OAuth Scope, its value will be again be different depending on your Identity Provider. In case of Google, you can enter `openid`.
+
+{% hint style="info" %}
+Please look at the list of allowed scopes in your Identity Provider's documentation, and enter the value of the least permissive scope. We only use the Access Token to verify that the user is authenticated, and we do not use the Access Token to fetch any further information. So, entering the least permissive scope is the best security recommendation.
+{% endhint %}
+
+Hit Save.
+
+Now, in GitBook, close the integrations modal and click on the Manage site button. Navigate to **Audience**, select **Authenticated access**, and choose OIDC as the backend. Then, click **Update audience**. Go to the site’s screen and click **Publish**.\
+\
+The site is now published behind authenticated access controlled by your Auth0 application. To try it out, click on Visit. You will be asked to sign in with OIDC, which confirms that your site is published behind authenticated access using Auth0.
diff --git a/publishing-documentation/authenticated-access/setting-up-okta.md b/publishing-documentation/authenticated-access/setting-up-okta.md
new file mode 100644
index 00000000..4523a380
--- /dev/null
+++ b/publishing-documentation/authenticated-access/setting-up-okta.md
@@ -0,0 +1,98 @@
+---
+description: Set up an Okta login screen for visitors to your docs.
+---
+
+# Setting up Okta
+
+{% hint style="warning" %}
+This guide takes you through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through the process of [enabling authenticated access](enabling-authenticated-access.md).
+{% endhint %}
+
+To setup your GitBook site with authenticated access using Okta, the process looks as follows:
+
+{% stepper %}
+{% step %}
+#### Create a new Okta application
+
+Create an Okta application from your Okta dashboard.
+{% endstep %}
+
+{% step %}
+#### Install and configure the Okta integration
+
+Install the Okta integration and add the required configuration.
+{% endstep %}
+
+{% step %}
+#### Configure Okta for adaptive content (optional)
+
+Configure Okta to work with adaptive content in GitBook.
+{% endstep %}
+{% endstepper %}
+
+### Create a new Okta application
+
+First, sign in to Okta platform (the admin version) and create a new app integration (or use an existing one) by clicking the Applications button in the left sidebar.
+
+
+
+Click Create App Integration and select OIDC - OpenID Connect as the Sign-In method. And then select Web Application as the application type.
+
+
+
+Name it appropriately and don't edit any other setting on that page. For assignments, choose the appropriate checkbox. Click Save.
+
+On the next screen, copy Client ID and Client Secret. Copy the Okta Domain right below your email address by clicking the dropdown in the top right.
+
+
+
+We will need these values to configure the Okta Integration.
+
+### Install and configure the Okta integration
+
+Navigate to the Integrations tab in the site you want to publish and locate the Okta integration or navigate directly to this [https://app.gitbook.com/integrations/VA-Okta](https://app.gitbook.com/o/d8f63b60-89ae-11e7-8574-5927d48c4877/s/zq8ynchcecIscc4uulgN/).
+
+
+
+Install the integration on your site.
+
+Upon installation on site, you will see a screen asking you enter the Client ID, Okta Domain, and Client Secret.
+
+
+
+For Client ID, Okta Domain (remove `https://`prefix, if any) and Client Secret, paste in the value you copied from Okta Dashboard.
+
+Click Save.
+
+Copy the URL displayed in the modal and enter it as a Sign-In redirect URI in Okta (as shown in the below screenshot). Hit Save.
+
+
+
+Now, in GitBook, close the integrations modal and click on the Manage site button. Navigate to **Audience**, select **Authenticated access**, and choose Okta as the backend. Then, click **Update audience**. Go to the site’s screen and click **Publish**.\
+\
+The site is now published behind authenticated access controlled by your Auth0 application. To try it out, click on Visit. You will be asked to sign in with Okta, which confirms that your site is published behind authenticated access using Auth0.
+
+### Configure Okta for adaptive content (optional)
+
+To enable Adaptive Content in your GitBook site with authenticated access, you’ll need to configure your Okta application to include relevant user data as claims in the authentication token.
+
+Claims are key-value pairs embedded in the token sent to GitBook. These claims can be used to dynamically tailor documentation based on the user’s role, plan, location, or any other identifying attribute.
+
+Okta supports multiple types of claims:
+
+* **Standard Claims**\
+ These are common claims (like `email`, `name`, or `groups`) that may be included by default but often need to be explicitly added to your token configuration for consistent availability.
+* **Custom Claims**\
+ You can define custom claims in Okta using [custom user attributes](https://help.okta.com/oie/en-us/Content/Topics/Directory/custom-user-profile-attributes.htm) or expression-based logic. These allow you to pass highly specific values—like plan tier, account ID, or internal team flags.
+* **Groups as Claims**\
+ You can also pass Okta groups as claims, which is especially useful when defining audience segments like “enterprise users” or “beta testers.” These can be filtered and mapped in your authorization server’s claim configuration.
+
+To add or customize claims in Okta:
+
+1. Open your Okta Admin Console.
+2. Navigate to **Security > API > Authorization Servers**.
+3. Edit the authorization server used for your GitBook site.
+4. Under the **Claims** tab, add rules to include the desired claims in the token.
+5. Make sure your GitBook site is reading and mapping those claims correctly.
+
+Once claims are being passed into GitBook, follow the steps in [Adapting your content](https://www.gitbook.com/docs/adaptive-content/configure-your-site) to define what content should be shown to whom.
diff --git a/publishing-documentation/custom-domain.md b/publishing-documentation/custom-domain.md
new file mode 100644
index 00000000..e6bdac6e
--- /dev/null
+++ b/publishing-documentation/custom-domain.md
@@ -0,0 +1,98 @@
+---
+description: Set a custom domain for your docs sites
+icon: globe-pointer
+---
+
+# Set a custom domain
+
+{% include "../.gitbook/includes/premium-and-ultimate-hint.md" %}
+
+{% hint style="warning" %}
+This page shows how to configure a custom domain and subdomain. If you would like to configure a custom subdirectory (such as `example.com/docs`), see the [setting-a-custom-subdirectory](setting-a-custom-subdirectory/ "mention") page.
+{% endhint %}
+
+By default, your sites are accessible on a `[subdomain].gitbook.io` domain.
+
+You can customize this by setting a custom domain, meaning your audience can access your documentation on a chosen domain.
+
+{% stepper %}
+{% step %}
+### Choose a subdomain
+
+When choosing a subdomain, you can either use `www` or a custom one. Some commonly used subdomains are:
+
+* `docs.example.com`
+* `help.example.com`
+* `developers.example.com`
+{% endstep %}
+
+{% step %}
+### Initiate the custom domain setup
+
+Navigate to the site for which you want to set the custom domain. Click **Settings,** then choose **Set up a custom domain.**
+
+From here, you'll see a window where you can enter the custom domain you chose in the first step. Type it out and click **Next.**
+{% endstep %}
+
+{% step %}
+### Configure the DNS
+
+At this stage, you'll see a window with three fields: **Type, Name, Target.**
+
+Those are the details you'll use to set your custom domain in your DNS provider. This is done _outside_ GitBook, in the provider you are using for your domain.
+
+Copy the contents of the **Name** and **Target** fields to use in your DNS provider. Each provider is different, so when in doubt, check directly with them how to add this record. You should be able to pick the **Type** of record from a list in your provider.
+
+After adding the record, it might take some time for the changes to propagate. We recommend **waiting at least 1 hour** before moving to the next step. Click **Next** when you are ready.
+{% endstep %}
+
+{% step %}
+### Finalize your setup
+
+After adding the record and it being propagated, it's time to go live! GitBook will verify the domain, the record you added and will automatically configure the SSL certificate for your domain.
+
+Once done, you'll receive a notification and can click **Finish**. You can also close the window if you need, and we'll send you a notification once the process is done on our side.
+{% endstep %}
+{% endstepper %}
+
+### Troubleshooting
+
+Setting up a custom domain can occasionally run into obstacles. Below, we outline frequent problems encountered during this process and provide detailed solutions to each of them.
+
+
+
+SSL error: an error occurred when provisioning your SSL certificate.
+
+When a custom domain is set for your organization, collection, or space, we set up an SSL certificate on our end so that your documentation will load securely, over HTTPS. \
+\
+This happens automatically when you set your custom domain — you do not need to purchase or configure an SSL certificate.
+
+Occasionally errors occur at this stage, usually when the CNAME record for the custom domain hasn't propagated.
+
+In these cases, we can recommend the following:
+
+1. Check that your CNAME record is set up correctly. \
+ Please review our page about configuring DNS to help you with this. \
+ If the CNAME record is incorrect, we won't be able to configure the SSL certificate and complete the custom domain set-up.
+2. Allow _**at least one hour**_ between configuring the CNAME record and finalizing the custom domain setup.
+3. Verify if the CNAME has propagated. You can try using a third-party DNS lookup tool, such as [WhatsMyDNS](https://www.whatsmydns.net/), to find out what the servers believe to be correct for your correct CNAME record.
+4. If you are using Cloudflare, please confirm that you don’t have the record proxied [as explained here](https://developers.cloudflare.com/fundamentals/setup/manage-domains/pause-cloudflare/#disable-proxy-on-dns-records).
+
+
+
+
+
+Domain already connected error: your subdomain is already configured for different content.
+
+A custom domain assigned to a site must be unique. Attempting to use the same custom domain in more than one location will result in an error.
+
+If this happens, you can click the link within the error message to look at the content the custom domain is already connected to. This may help you to decide what to do next.
+
+It’s also possible that you might not have access to the content — if that’s the case, contact the support team and they can help you with your next steps.
+
+The solution to this error will always be one of two things, however:
+
+1. Choose a different custom domain; or
+2. Disconnect the custom domain from the content it is already connected to, then reconnect it to the new content.
+
+
diff --git a/publishing-documentation/customization/README.md b/publishing-documentation/customization/README.md
new file mode 100644
index 00000000..d936f610
--- /dev/null
+++ b/publishing-documentation/customization/README.md
@@ -0,0 +1,51 @@
+---
+description: Create branded documentation with a custom logo, fonts, colors, links and more
+icon: palette
+---
+
+# Site customization
+
+{% include "../../.gitbook/includes/customization-premium-and-ultimate-hint.md" %}
+
+You can customize the appearance of your published documentation, match the user interface to the language of your content, and more.
+
+You can apply customizations to your entire docs site as a site-wide theme, or to individual variants and site sections.
+
+
You can create all kinds of site designs using GitBook’s built-in customization options.
+
+### Customizing sites with multiple sections or variants
+
+If you have a docs site with with multiple sections or variants, you can control the customization of each one individually.
+
+Select the whole site or a specific site section using the drop-down menu at the top of the **Customization** panel.
+
+* **Site-wide settings** – These automatically apply to all linked spaces.
+* **Section or variant specific settings** – If you’re using site sections or variants, you’re can set specific customization that will override the default site-wise setting.
+
+
The customization panel in GitBook.
+
+{% hint style="warning" %}
+Changes you make to specific site sections will override the site-wide customization settings, even if you change the site-wide setting again later.
+
+You can reset customization overrides back to the site-wide default by clicking the **Reset** button next to the space selector.
+{% endhint %}
+
+### What counts as ‘Advanced customization’?
+
+Every GitBook user can take advantage of basic customization options on their docs site. Premium or Ultimate site plan users can also use advanced customization features to further tweak their docs to match their brand.
+
+Advanced customization options include:
+
+* **Custom logo** – Add a logo that replaces the emoji and title at the top of your docs site.
+* **Icons** - Change the weight and style of page icons in your docs site.
+* **Custom font** – Change the font of your docs to one of the built-in options.
+* **Footer** – Add a custom logo, copyright text and navigation to a footer at the bottom of your documentation.
+* **Bold and Gradient themes** – Change the background color for your header, or add a gradient background to your entire site with these new themes.
+
+### What cannot be customized?
+
+The options above provide lots of ways for you to customize your space, but there are a few things that you won’t be able to customize, regardless of [your chosen plan](../../account-management/plans/).
+
+1. It’s not possible to customize the layout of the elements on the page (However, it _is_ possible to [hide certain elements on specific pages](../../creating-content/content-structure/page.md)).
+2. It’s not possible to insert custom code (such as CSS, HTML or JS) directly into your GitBook site. We already integrate with a number of popular tools, and offer [rich embeds](../../creating-content/blocks/embed-a-url.md) for many more.
+3. It’s not possible to remove the small “Powered by GitBook” link that appears in published documentation.
diff --git a/publishing-documentation/customization/extra-configuration.md b/publishing-documentation/customization/extra-configuration.md
new file mode 100644
index 00000000..2d847b8c
--- /dev/null
+++ b/publishing-documentation/customization/extra-configuration.md
@@ -0,0 +1,45 @@
+---
+description: Configure extra options for your published documentation.
+---
+
+# Extra configuration
+
+### Localize user interface
+
+You can select from a list of languages to localize the user interface of your published content. This applies translations to the non-custom areas of the interface.
+
+This setting will _not_ auto-translate your actual content, but it can help match the interface to the language you’re writing in. To learn more about translating your content, head to the [Translations](../../creating-content/translations.md) section.
+
+Is there a language we don’t yet offer that you’d like to see included? [Let us know](https://github.com/GitbookIO/gitbook/issues), or [contribute your own translation](https://www.gitbook.com/solutions/open-source)!
+
+### External Links
+
+This setting controls the behaviour when your site users click an external link. By default, they will open in the same tab, but you can switch this to open in a new tab if that's your preference.
+
+### Page actions
+
+Page actions adds a page-level dropdown to every page of your docs, allowing users to perform quick actions on a page's content — ideal for using your docs content as context within an AI prompt.
+
+You can disable this option from the **Configure** tab if you do not wish to show page options in your published docs.
+
+
+
+#### Open in AI providers
+
+Displays an action to open ChatGPT or Claude with the page content.
+
+#### Copy/View as Markdown
+
+Displays an action to copy or view the page as Markdown.
+
+#### Edit on GitHub/GitLab
+
+If your space is connected to a Git repository, you can optionally show a link for your users to contribute to your documentation from your linked repository.
+
+#### Export PDF
+
+Allow visitors to export a PDF of your documentation. See [PDF export](../../collaboration/pdf-export.md) for more info.
+
+### Privacy Policy
+
+You can link to your own privacy policy to help visitors understand how your GitBook content uses cookies and how you protect their privacy. If you choose not to set one, your site will default to [GitBook’s privacy policy](https://gitbook.com/docs/policies/privacy-and-security/statement/cookies).
diff --git a/publishing-documentation/customization/icons-colors-and-themes.md b/publishing-documentation/customization/icons-colors-and-themes.md
new file mode 100644
index 00000000..e834885d
--- /dev/null
+++ b/publishing-documentation/customization/icons-colors-and-themes.md
@@ -0,0 +1,126 @@
+---
+description: Customize icons, colors, themes and more.
+---
+
+# Icons, colors, and themes
+
+### Title, icon and logo
+
+
+
+**Title**
+
+You can set any title you choose for your space. Note: this setting will only affect the title that displays _in the published documentation_. If you want to edit the title in the GitBook app, close the customize menu and edit it at the top of the space.
+
+**Icon**
+
+You can set an emoji, or upload an icon of your own. The icon you set in the **Customization** menu will be used as the favicon for your docs site.
+
+{% hint style="info" %}
+This setting will only affect the icon that displays _in the published documentation_. If you want to edit the icon used within the GitBook app, you can do so when editing content in the space itself.
+{% endhint %}
+
+**Custom logo** **(Premium & Ultimate)**
+
+You can replace _both_ the published space’s title and icon with a custom logo so that your documentation better reflects your own branding — and you can upload two versions: one for light mode, and one for dark mode.
+
+{% hint style="info" %}
+#### What’s the difference between the icon and logo options?
+
+The icon setting lets you upload a small, 132×132 px image, which will appear _alongside_ your space title and function as your site’s favicon. The custom logo option lets you upload a larger image (we recommend at least 600 px wide), which will completely replace any icon and title you’ve set.
+{% endhint %}
+
+### Themes
+
+Themes let you customize the color scheme of your published content for both light and dark mode. There are four themes to choose from. The colors of your site will be directly impacted by the **primary color** and **tint** that you choose. These two selections affect various parts of the interface and can completely change the look and feel of your site.
+
+
+
+#### Clean
+
+A modern theme featuring translucency and minimally styled elements. Your primary color (or tint) affects links and other highlighted interface elements.\
+\&#xNAN;_Clean is available for all sites and is the default theme._
+
+#### Muted
+
+A sophisticated theme with decreased contrast between elements. The site background is more pronounced and blends in with the foreground, and some elements feature an inverted look — all based on your primary color (or tint).\
+\&#xNAN;_Muted is available for all sites._
+
+#### Bold **(Premium & Ultimate)**
+
+A high‑impact theme with prominent colors and strong contrasts. Your primary color (or tint) will be used for the header of the site, and other highlighted elements like icons are colored along with it.\
+\&#xNAN;_Bold is only available for Premium or Ultimate sites._
+
+#### Gradient **(Premium & Ultimate)**
+
+A trendsetting theme featuring a gradient background and splashes of color. The gradient and highlighted elements will be colored by your primary color (or tint).\
+\&#xNAN;_Gradient is only available for Premium or Ultimate sites._
+
+### Colors
+
+
+
+#### Primary color
+
+Your site’s primary color will affect the styling of highlighted interface items and navigational elements like links, the current page and section, breadcrumbs, and primary header buttons. GitBook automatically adjusts colors on individual elements for readability if the contrast with the background is too low or when a visitor’s system requests higher contrast.
+
+#### Tint color
+
+Your site’s tint color will subtly change the color of all text and icons across your entire site — including header links, icon color, and UI elements like the **Ask or search** bar. The tint color will _not_ affect navigational elements like links and buttons, which always use the primary color. In the **Tint color** section you’ll see suggested colors based on your primary color selection; you can select one to preview it, choose your primary color as your tint, or pick a completely custom color with the color picker.
+
+#### Semantic colors
+
+Semantic colors are applied to hint blocks within your published content. You can change the background color of each hint style; these changes will only be reflected on the published site you’re customizing. Hint blocks in the GitBook editor will always remain in their assigned colors.
+
+### Modes
+
+**Show mode toggle**
+
+Enable this if you want visitors to manually toggle between light and dark mode. Readers can find the toggle at the bottom of any published page, on both desktop and mobile.
+
+**Default mode**
+
+Choose whether visitors see your content in light or dark mode by default. If **Show mode toggle** is enabled, they can switch modes; if disabled, they’ll only see the mode you choose here.
+
+_Note: to change the theme within the GitBook app, go to your Settings menu at the bottom of the sidebar._
+
+### Site styles
+
+
+
+**Font family** **(Premium & Ultimate)**
+
+Choose a font family for your published content from a curated list of popular options.
+
+**Custom fonts** **(Ultimate)**
+
+Upload your own fonts to align your published content with your brand’s style guide. To upload a font, click **Add custom font** and follow the instructions. You must upload a font file for both regular and bold weights.
+
+GitBook currently supports `.woff` and `.woff2`. For other formats, please contact [support@gitbook.com](mailto:support@gitbook.com).
+
+**Icons** **(Premium & Ultimate)**
+
+When using page icons, set the weight and style of the displayed icons here.
+
+**Corner style**
+
+Choose either rounded or straight corners to match your brand’s style preferences.
+
+**Link style**
+
+Choose between two link designs:
+
+* **Default:** highlights the entire link in your primary or tint color.
+* **Accent:** adds a colored underline to the link, leaving the text color unchanged.
+
+### Sidebar styles
+
+
+
+**Background style**
+
+Choose the background style for the sidebar container. The color is derived from your selected theme.
+
+**List style**
+
+Choose the style for the sidebar list and its selected items.
diff --git a/publishing-documentation/customization/layout-and-structure.md b/publishing-documentation/customization/layout-and-structure.md
new file mode 100644
index 00000000..ccf96bcf
--- /dev/null
+++ b/publishing-documentation/customization/layout-and-structure.md
@@ -0,0 +1,45 @@
+---
+description: Customize the layout and structure of your published documentation.
+---
+
+# Layout and structure
+
+### Header
+
+
+
+**Search bar**
+
+Change the position and look of the search bar between prominent (centered in the header) and subtle (located in the upper right corner). Turning off the header entirely will place the search bar in the sidebar instead.
+
+**Navigation**
+
+Add header links to your site. You could use header links to point to important parts of your documentation, or link back to your main website.
+
+You can choose what appearance you would like your link to have—normal link, primary button, or secondary button. When enabled, simply add a title and a URL for each link. We support two levels of header navigation, meaning you can have sub‑links that appear in a dropdown menu.
+
+### Announcement (Premium & Ultimate)
+
+Toggle this option on to add an announcement banner to the top of your published site. You can add a message and optionally include a link and call to action, which will appear after your message in the banner.
+
+You can also change the announcement style using the same options as hint blocks—Info, Warning, Danger, and Success. The color of these styles is determined by your semantic colors settings.
+
+### Pagination
+
+Control the display of the “previous” and “next” buttons that appear at the bottom of each page in your space. You can also set this feature for specific pages.
+
+### Footer (Premium & Ultimate)
+
+
+
+**Logo**
+
+Add your logo or another image in the footer.
+
+**Copyright text**
+
+Add copyright information to your footer.
+
+**Navigation**
+
+Add links in your footer, organized into multiple sections. Similar to the header, add a title and URL for each link, and include a section title for each group of links.
diff --git a/publishing-documentation/gitbook-assistant/README.md b/publishing-documentation/gitbook-assistant/README.md
new file mode 100644
index 00000000..386f92a5
--- /dev/null
+++ b/publishing-documentation/gitbook-assistant/README.md
@@ -0,0 +1,71 @@
+---
+description: Embed the GitBook Assistant in your website or app.
+icon: messages
+---
+
+# GitBook Assistant
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+
The GitBook Assistant
+
+GitBook Assistant gives your users fast, accurate answers about your documentation using natural language. It’s personalized on your users, can be embedded into your website or product, and available in the sidebar of your docs.
+
+Think of it as a product expert available to all of your users, in the places and times they need it most.
+
+The Assistant uses agentic retrieval to understand the context of the query based on the user’s current page, previously-read pages, and previous conversations they’ve had.
+
+GitBook Assistant is trained on your documentation, but you can also add external sources to expand it’s context and knowledge and give better answers.
+
+
+
+### Using GitBook Assistant in GitBook
+
+Users can access GitBook Assistant in three ways:
+
+* Press ⌘ + I on Mac or Ctrl + I on PC
+* Click the **GitBook Assistant** button next to the **Ask or search…** bar
+* Type a question into the **Ask or search…** bar and choose the ‘Ask…’ option at the top of the menu.
+
+{% if visitor.claims.unsigned.reflag.EMBED_ASSISTANT_PANEL == true %}
+### Add GitBook Assistant to your website or app
+
+Not only is GitBook Assistant available in GitBook sites, but an embeddable version is available to help you tie your product and product knowledge closer together.
+
+The embeddable GitBook Assistant allows you to bring your product docs, assistant, and custom tools into your product or website to help your users with things like onboarding, product suggestions when they get stuck, and contextual solutions based on the user who’s using it.
+
+You can also customize GitBook Assistant in many ways, including configuring custom tools to seamlessly integrate the assistant alongside your product.
+
+Head to the [next section](adding-the-assistant-to-your-website-or-app.md) to learn more about adding the assistant to your product.
+{% endif %}
+
+### Extend GitBook Assistant with MCP servers
+
+You can also choose to add external data sources to GitBook Assistant to give it more context and data to pull answers from. You can do this by connecting Assistant to MCP servers for external platforms, such as:
+
+* Your community (Slack, Discord, GitHub Communities etc)
+* Support tools (Intercom etc)
+* Your future product roadmap (GitHub, Linear etc)
+* Docs for external integrations with products
+
+To add an MCP server to GitBook Assistant, follow these steps:
+
+{% stepper %}
+{% step %}
+#### Open your site’s settings
+
+Navigate to your site dashboard and choose the **Settings** option from the site header. Then choose the **AI & MCP** section from the left-hand menu
+{% endstep %}
+
+{% step %}
+#### Add a new server
+
+At the bottom of the page is a table showing all the connected MCP servers. To add a new server, click **Add MCP server**
+{% endstep %}
+
+{% step %}
+#### Choose your MCP server
+
+To add your server you’ll need to give it a name, add the URL for the server, and configure the HTTP headers that will be sent along with the request to the server when a user submits a query.
+{% endstep %}
+{% endstepper %}
diff --git a/publishing-documentation/gitbook-assistant/adding-the-assistant-to-your-website-or-app.md b/publishing-documentation/gitbook-assistant/adding-the-assistant-to-your-website-or-app.md
new file mode 100644
index 00000000..b790b572
--- /dev/null
+++ b/publishing-documentation/gitbook-assistant/adding-the-assistant-to-your-website-or-app.md
@@ -0,0 +1,65 @@
+---
+if: visitor.claims.unsigned.reflag.EMBED_ASSISTANT_PANEL == true
+---
+
+# Adding the assistant to your website or app
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+The GitBook Assistant can be embedded directly into your website or app, so your users always have access to product knowledge and your documentation, right where they need it.
+
+You can add it as a script, integrate it as a package, or drop in ready-made React components.
+
+### Embedding with a script
+
+The quickest way to add the GitBook Assistant to your website or app is by adding it through a script. Every GitBook docs site includes a ready-to-use script for embedding the Assistant as a widget.
+
+You’ll find the embed script in your docs site’s **Settings**, under the **AI & MCP tab**, or you can copy it from the example below (replacing `docs.company.com` with your docs site url):
+
+```html
+
+
+```
+
+Once added, the Assistant will appear as a widget on your site, giving visitors direct access to your documentation and more.
+
+### Embedding with NPM
+
+If you’d prefer more control and want to work at the application level, you can install the GitBook embed package from npm.
+
+```bash
+npm install @gitbook/embed
+```
+
+After importing it into your application, you’ll be able to create an iFrame, and set it’s URL to an initialized GitBook Assistant window.
+
+```javascript
+import { createGitBook } from '@gitbook/embed';
+
+const gitbook = createGitBook({
+ siteURL: 'https://docs.company.com'
+});
+
+const iframe = document.createElement('iframe');
+iframe.src = gitbook.getFrameURL();
+
+const frame = gitbook.createFrame(iframe);
+```
+
+This gives you full control over where and how the Assistant is displayed in your app.
+
+### Using React components
+
+For React projects, we provide prebuilt components that make embedding even simpler. After installing the NPM package, you can add the Assistant with just a few lines:
+
+```jsx
+import { GitBookProvider, GitBookAssistantFrame } from '@gitbook/embed/react';
+
+
+
+
+```
+
+This setup automatically manages the Assistant’s context, so your users can explore documentation seamlessly without leaving your product.
diff --git a/publishing-documentation/gitbook-assistant/creating-custom-tools.md b/publishing-documentation/gitbook-assistant/creating-custom-tools.md
new file mode 100644
index 00000000..8ecd4165
--- /dev/null
+++ b/publishing-documentation/gitbook-assistant/creating-custom-tools.md
@@ -0,0 +1,65 @@
+---
+if: visitor.claims.unsigned.reflag.EMBED_ASSISTANT_PANEL == true
+---
+
+# Creating custom tools
+
+Custom tools allow you to dispatch web or product actions for different scenarios. For example, you can build a custom tool that instructs the assistant to call APIs, perform product actions, open other tools, and more.
+
+Tools can be defined in the `configure` or `registerTool` call from `GitBook`.
+
+Let’s look at an example:
+
+```javascript
+window.GitBook.registerTool({
+ // Register the tool with a name and description.
+ name: "create_ticket",
+ description:
+ "Create a ticket for the user. You MUST fill in the ticket_issue field.",
+
+ // The input schema is data that can be accessed in the execute function.
+ inputSchema: {
+ type: "object",
+ properties: {
+ ticket_issue: {
+ type: "string",
+ description:
+ "The issue to create the ticket for. If unknown, ask the user first.",
+ },
+ },
+ },
+
+ // An optional confirmation button that shows before the execute function is run.
+ confirmation: { icon: "ticket", label: "Create ticket" },
+
+ // The execute function is the function that will be called when the tool is used.
+ execute: async (input) => {
+ const { ticket_issue } = input;
+
+ // Create a ticket with the user's issue
+ const ticketId = await createTicket(ticket_issue);
+
+ return {
+ // The output is passed back to the AI.
+ output: {
+ ticketId: ticketId,
+ status: "success",
+ },
+ // The summary is passed back to the user.
+ summary: {
+ icon: "ticket",
+ text: `Created ticket for ${ticket_issue}`,
+ },
+ };
+ },
+});
+
+```
+
+#### How it works
+
+Any tools provided to the assistant when configuring it will be available through AI - meaning the assistant is able to intelligently execute your tools when it fits the context.
+
+In the example above, when the assistant identifies that the user needs to create a support ticket, ask the user what the issue is, and then execute a function that logs a ticket.
+
+
Key
Description
description
Allows the GitBook assistant to know the context on when to use the tool being defined.
inputSchema
Define data you would like the tool to have access to (like email addresses or messages). Can be accessed in the input argument in the execute call.
confirmation
An optional confirmation button that allows you to specify user interaction before firing the execute function.
execute
The function that runs when the tool is called. Has access to an input argument that can contain user-input data defined in the inputSchema.
diff --git a/publishing-documentation/gitbook-assistant/customizing-the-assistant.md b/publishing-documentation/gitbook-assistant/customizing-the-assistant.md
new file mode 100644
index 00000000..d1639667
--- /dev/null
+++ b/publishing-documentation/gitbook-assistant/customizing-the-assistant.md
@@ -0,0 +1,56 @@
+---
+if: visitor.claims.unsigned.reflag.EMBED_ASSISTANT_PANEL == true
+---
+
+# Customizing the assistant
+
+After adding the assistant to your website or app, you can further customize the experience by adding things like a welcome message, actionable buttons to the header, and suggestions to nudge your users with contextual questions.
+
+### Adding a welcome message
+
+To add a welcome message, you can use the `welcomeMessage` key when initializing the GitBook Assistant.
+
+```javascript
+window.GitBook('configure', {
+ welcomeMessage: "Welcome to our help center! How can we assist you today?",
+}
+```
+
+### Adding buttons
+
+Adding buttons to the assistant allows you to give users extra actions in the UI of the assistant. You can add icons from [Font Awesome](https://fontawesome.com/), and any buttons will appear in the assistant’s header once loaded.
+
+```javascript
+window.GitBook('configure', {
+ buttons: [
+ {
+ label: 'Contact Support',
+ icon: 'envelope',
+ onClick: () => {
+ window.open('mailto:support@example.com', '_blank');
+ }
+ },
+ {
+ label: 'Documentation',
+ icon: 'book',
+ onClick: () => {
+ window.open('https://docs.example.com', '_blank');
+ }
+ }
+ ],
+}
+```
+
+### Adding suggestions
+
+You can also add suggestions to the assistant, which will show up as clickable prompts for your users to use when the assistant loads.
+
+```javascript
+window.GitBook('configure', {
+ suggestions: [
+ 'Help me get started with my new account',
+ 'How do I reset my password?',
+ 'What are your pricing plans?'
+ ],
+}
+```
diff --git a/publishing-documentation/gitbook-assistant/reference.md b/publishing-documentation/gitbook-assistant/reference.md
new file mode 100644
index 00000000..88090b0b
--- /dev/null
+++ b/publishing-documentation/gitbook-assistant/reference.md
@@ -0,0 +1,184 @@
+---
+if: visitor.claims.unsigned.reflag.EMBED_ASSISTANT_PANEL == true
+---
+
+# Reference
+
+The GitBook Assistant also exposes helper functions that further allow it to interact with your app.
+
+### Main Functions
+
+#### Show the widget
+
+Display the GitBook widget if it has been hidden.
+
+**Example:**
+
+```js
+window.GitBook('show');
+```
+
+#### Hide the widget
+
+Hide the GitBook widget without unloading it.
+
+**Example:**
+
+```js
+window.GitBook('hide');
+```
+
+#### Open the window
+
+Open the GitBook assistant window.
+
+**Example:**
+
+```js
+window.GitBook('open');
+```
+
+#### Close the window
+
+Close the GitBook assistant window.
+
+**Example:**
+
+```js
+window.GitBook('close');
+```
+
+#### Toggle the window
+
+Toggle the GitBook assistant window open or closed.
+
+**Example:**
+
+```js
+window.GitBook('toggle');
+```
+
+#### Unload the widget
+
+Completely remove the GitBook widget from your site.
+
+**Example:**
+
+```js
+window.GitBook('unload');
+```
+
+### Navigation Functions
+
+#### `window.GitBook('navigateToPage', path)`
+
+Navigate to a specific page within your GitBook docs by its path.
+
+**Parameters:**
+
+* `path` (string): The path to the page you want to navigate to
+
+**Example:**
+
+```javascript
+// Navigate to the getting started guide
+window.GitBook('navigateToPage', '/getting-started');
+
+// Navigate to a specific API documentation page
+window.GitBook('navigateToPage', '/api/authentication');
+
+// Navigate to FAQ section
+window.GitBook('navigateToPage', '/faq/billing');
+```
+
+#### `window.GitBook('navigateToAssistant')`
+
+Navigate directly to the AI assistant interface.
+
+**Example:**
+
+```javascript
+// Open the assistant chat
+window.GitBook('navigateToAssistant');
+
+// You might use this in response to a button click
+document.getElementById('help-button').addEventListener('click', () => {
+ window.GitBook('navigateToAssistant');
+});
+```
+
+### Chat Functions
+
+#### `window.GitBook('postUserMessage', message)`
+
+Post a message to the chat as if the user typed it.
+
+**Parameters:**
+
+* `message` (string): The message to post to the chat
+
+**Example:**
+
+```javascript
+// Send a predefined message
+window.GitBook('postUserMessage', 'How do I reset my password?');
+
+// Send a message based on user action
+function askAboutBilling() {
+ window.GitBook('postUserMessage', 'I have questions about my billing');
+}
+
+// Send a message with context
+const userPlan = 'premium';
+window.GitBook('postUserMessage', `I'm on the ${userPlan} plan and need help with advanced features`);
+```
+
+#### `window.GitBook('clearChat')`
+
+Clear all messages from the current chat session.
+
+**Example:**
+
+```javascript
+// Clear the chat
+window.GitBook('clearChat');
+
+// Clear chat and start fresh conversation
+function startNewConversation() {
+ window.GitBook('clearChat');
+ window.GitBook('postUserMessage', 'Hello, I need help with a new issue');
+}
+
+// Clear chat when switching contexts
+document.getElementById('new-topic').addEventListener('click', () => {
+ window.GitBook('clearChat');
+ window.GitBook('navigateToAssistant');
+});
+```
+
+### Event Handling
+
+#### `window.GitBook('on', event, listener)`
+
+Register an event listener for GitBook events.
+
+**Parameters:**
+
+* `event` (string): The event name to listen for
+* `listener` (function): The callback function to execute when the event occurs
+
+**Example:**
+
+```javascript
+// Listen for page navigation
+window.GitBook('on', 'navigate', (data) => {
+ console.log('Navigated to:', data.path);
+ // Update breadcrumbs or analytics
+});
+
+// Listen for tool usage
+window.GitBook('on', 'tool_used', (data) => {
+ console.log('Tool used:', data.toolName);
+ // Log tool usage for analytics
+});
+```
diff --git a/publishing-documentation/insights.md b/publishing-documentation/insights.md
new file mode 100644
index 00000000..d53ebd2b
--- /dev/null
+++ b/publishing-documentation/insights.md
@@ -0,0 +1,85 @@
+---
+description: View analytics and insights related to your published documentation’s traffic
+icon: chart-line-up
+---
+
+# Site insights
+
+{% include "../.gitbook/includes/premium-and-ultimate-hint.md" %}
+
+Insights give you information on the content you've published and how it performs. It's split up between different sections — **Traffic**, **Pages & feedback**, **Search**, **Ask AI**, **Links**, and **OpenAPI**.
+
+You can see a top-level overview of your insights on the **Overview** tab of your site’s dashboard, with a globe that shows views in the last hour by location.
+
+Click the **Insights** tab in the site header to find more detailed insights for your site.
+
+
The site insights dashboard.
+
+### Filters & groups
+
+You can add filters or group your data to view it in specific ways. For example, you could look at search data within a specific site section, or filter your traffic data by country, device, browser and more.
+
+By combining filters and groups, you can drill down in to precise analytics data to track the events that you are important to you.
+
+### View by custom time periods
+
+You can use the drop-down menu on the right of the Insights screen to change the time period between the last 24 hours, 7 days, 30 days or 3 months.
+
+To view the data over a custom time period, click the **Select custom date range** button to the right of the menu and choose your custom time period using the calendar that appears.
+
+### Types of data
+
+The Insights tab is split into six sections, each focused on a specific data type.
+
+#### Traffic
+
+GitBook tracks page views to help you understand the popularity and reach of your content. Each time a user visits a page on your docs site, it is counted as a page view.
+
+Page views are critical for assessing the effectiveness of your content strategy and optimizing your documentation based on user interest. It’s split up between different views and profiles, including countries, languages, browsers, and more.
+
+{% hint style="success" %}
+Throughout the insights tab you will see Events and Visitor metrics. **Events** indicate the total number of instances for any given category, while **Visitors** indicates the unique users performing the actions.
+
+In the context of page views, Events would be total amount of page views, and Visitors would be the count of distinct users performing a page view.
+{% endhint %}
+
+#### Pages & Feedback
+
+Pages & feedback allow you to see a high-level representation of how your users rate your content. You’ll see an overview of all of your site’s sections and variants, and after enabling [page rating](site-settings.md#page-ratings-pro-and-enterprise-plans) in the **Customize** menu for a site, you can see each page’s average feedback rating.
+
+If you want to use or analyze this data further outside of GitBook, click **Download CSV** to download a `.csv` file to your device.
+
+You can also see a list of comments left from visitors who rate your pages, to get actionable insights on how your docs can be improved.
+
+{% hint style="info" %}
+**Why can’t I see any feedback data for my site?**\
+We only display data for published sites with page ratings enabled. If your site is not published or does not have page ratings enabled, you won’t see any insights.
+{% endhint %}
+
+#### Broken URLs
+
+Broken URLs shows any incoming links from external sources that are resulting in a ‘Page not found’ error. These may be mistyped URLs, outdated links with no redirects, or spam links.
+
+If a broken link points to a topic that exists somewhere else in your documentation, or you simply want to direct the traffic to your primary docs, you can set up [site redirects](site-redirects.md) to point those visitors in the right direction.
+
+#### Search
+
+You can measure and improve your documentation by checking which keywords are used the most by users searching your documentation. This view allows you to see what keywords are performing the best, and which ones you could improve on.
+
+The information here can be helpful for informing your content architecture, making certain parts of your documentation easier to find without search, or adding additional content to existing pages based on what your visitors are searching for.
+
+#### Ask AI
+
+The [Ask AI](../creating-content/searching-your-content/gitbook-ai.md) section allows you to see what your users are asking for when using GitBook AI. This insight helps you identify common questions, uncover gaps in your documentation, and improve content to better meet user needs.
+
+You can also see how users are rating the answers that AI gives to their questions. By looking at these queries and their ratings, you can refine your documentation structure, enhance discoverability, and identify areas that would benefit from more documented information.
+
+#### Links
+
+GitBook tracks links to help you understand how users interact with external resources in your documentation. This feature provides insights into external links, their domains, and their placement within your docs, such as in the header, footer, or sidebar. Analyzing link usage can help you optimize navigation, improve content accessibility, and refine your documentation strategy based on user engagement.
+
+#### OpenAPI
+
+The [OpenAPI](../api-references/openapi/) analytics view in GitBook provides insights into how users engage with your API documentation.
+
+It tracks interactions such as endpoint views, parameter searches, and request explorations, helping you understand which parts of your API are most accessed and where users may need more clarity. These insights enable you to refine your documentation, improve developer experience, and ensure your API content is effectively meeting user needs.
diff --git a/publishing-documentation/llm-ready-docs.md b/publishing-documentation/llm-ready-docs.md
new file mode 100644
index 00000000..e5f12d5e
--- /dev/null
+++ b/publishing-documentation/llm-ready-docs.md
@@ -0,0 +1,74 @@
+---
+description: Providing an LLM-friendly version of your docs site
+icon: user-robot
+---
+
+# LLM-ready docs
+
+We’re building features that make it easier for Large Language Models (LLMs) to ingest and work with your documentation content.
+
+As LLMs become increasingly important for information retrieval and knowledge assistance, ensuring your documentation is LLM-friendly can significantly improve how these models understand and represent your products or services.
+
+LLM-optimized documentation ensures that AI systems like ChatGPT, Claude, Cursor, and Copilot can retrieve and provide accurate, contextual responses about your product or API.
+
+## .md pages
+
+With GitBook, all of the pages of your docs site are automatically available as markdown files. If you add the `.md` extension to any page, you will see the content of that page rendered in markdown which you can pass to an LLM for more efficient processing than an HTML file.
+
+Check out the .md file for this page
+
+## llms.txt
+
+[llms.txt](https://llmstxt.org/) is a proposed standard for making web content available in text-based formats that are easier for LLMs to process. You can access the `llms.txt` page by appending `/llms.txt` to the root URL of your docs site.
+
+The `llms.txt` file serves as an index for your documentation site, providing a comprehensive list of all available markdown-formatted pages. With this file, you make it easier for LLMs to efficiently discover and process your documentation content.
+
+Check out the /llms.txt for the GitBook docs
+
+## llms-full.txt
+
+Where the `llms.txt` file contains an index of all the page URLs and titles of of your documentation site, the `llms-full.txt` contains the full content of your documentation site in one file that can be passed to LLMs as context.
+
+Check out the /llms-full.txt file for the GitBook docs
+
+LLMs can use this index to navigate directly to the markdown versions of your pages, allowing them to incorporate your documentation into their context without needing to parse HTML.
+
+## MCP server
+
+GitBook automatically exposes a Model Context Protocol (MCP) server for every published space. MCP gives AI tools a structured way to discover and retrieve your docs as resources — no scraping required.
+
+Your MCP server can be reached by appending `/~gitbook/mcp` to the URL of the root of your docs site. For instance, the GitBook docs MCP server is located at `https://gitbook.com/docs/~gitbook/mcp`.
+
+{% hint style="info" %}
+Visiting this URL in your browser will result in an error. Instead, you can share this with tools that can make HTTP requests, like LLMs or IDEs.
+{% endhint %}
+
+Learn more by reading [mcp-servers-for-published-docs.md](mcp-servers-for-published-docs.md "mention").
+
+## Tips for optimizing your docs for LLMs
+
+Now that your GitBook site automatically generates `.md` pages, `llms.txt`, and `llms-full.txt` files, these best practices will help LLMs effectively understand and work with your content.
+
+By using these optimizations, you may also improve your documentation’s performance in AI-powered search engines and generative engine optimization (GEO).
+
+The best part? These guidelines will generally make your docs easier for people to read as well.
+
+### Use clear, hierarchical structure
+
+Break up your content with good headings (H1, H2, H3) and don’t just write giant walls of text. Bullet points, numbered lists and shorter paragraphs make everything easier to read.
+
+### Write concise, jargon-free content
+
+Keep it simple and skip complex technical terms unless you really need them. LLMs do much better when you say what you mean without adding fluff.
+
+### Include practical examples
+
+Show, don’t just tell. Code snippets, API examples, and real scenarios help LLMs — and your users — understand how things actually work in practice.
+
+### Keep content current and accurate
+
+Nobody likes outdated docs. Regular updates mean LLMs won’t give people wrong information about your latest features and updates.
+
+### Test with AI tools
+
+Actually try asking ChatGPT or Claude questions about your docs to see how well they understand your content. You might be surprised by what works and what doesn’t.
diff --git a/publishing-documentation/mcp-servers-for-published-docs.md b/publishing-documentation/mcp-servers-for-published-docs.md
new file mode 100644
index 00000000..f5ee163f
--- /dev/null
+++ b/publishing-documentation/mcp-servers-for-published-docs.md
@@ -0,0 +1,64 @@
+---
+icon: server
+---
+
+# MCP servers for published docs
+
+Every published GitBook site automatically includes a Model Context Protocol (MCP) server.
+
+This allows AI assistants to access your documentation content directly, making it easy for tools like Claude Desktop, Cursor, and VS Code extensions to answer questions using your docs.
+
+The MCP server is available at your site’s URL with `/~gitbook/mcp` appended. For example, GitBook’s docs are located at `https://gitbook.com/docs`, so the MCP server is at `https://gitbook.com/docs/~gitbook/mcp`.
+
+{% hint style="info" %}
+Visiting this URL in your browser will result in an error. Instead, you can share this with tools that can make HTTP requests, like LLMs or IDEs.
+{% endhint %}
+
+### Connecting an AI assistant
+
+{% stepper %}
+{% step %}
+#### Find your MCP server URL
+
+Take your published GitBook site URL and add `/~gitbook/mcp` to the end.
+{% endstep %}
+
+{% step %}
+#### Configure your AI tool
+
+Add the MCP server URL to your AI assistant’s settings. Each tool has a slightly different setup process, so you should check out the docs for your tool of choice to see how to configure an MCP server for it.
+{% endstep %}
+
+{% step %}
+#### Start using your docs
+
+Once connected, your AI assistant can search through your documentation, retrieve specific pages, and answer questions using your content. The assistant will have real-time access to your published documentation.
+{% endstep %}
+{% endstepper %}
+
+### Requirements
+
+Your GitBook site must be published for the MCP server to work. The server only provides access to published content, never drafts or unpublished changes.
+
+Your AI tool needs to support the Model Context Protocol and be able to make HTTP requests to your site. Most modern AI assistants that support MCP will work with GitBook’s servers.
+
+The MCP server respects your site’s visibility settings. If your site is public, the MCP server is publicly accessible. If your site requires authentication, the MCP server will too.
+
+### Enable or disable easy MCP linking
+
+In the **Page actions** section of your [Customization](customization/) settings, you can enable the **Connect with MCP server** option. This enables visitors to your docs site to quickly copy a link to your site's MCP server right from [the Page actions menu](customization/extra-configuration.md#page-actions).
+
+### Privacy and access
+
+The MCP server only provides read-only access to your published documentation. It doesn’t expose any user data, analytics, or internal GitBook information.
+
+Only the latest published version of your content is available through the MCP server. Draft content and unpublished changes remain private until you publish them.
+
+### Common issues
+
+If your AI assistant can’t connect to your MCP server, first check that your GitBook site is published and accessible. The URL should respond when you visit it in a browser.
+
+Make sure you’re using the correct URL format with `/~gitbook/mcp` at the end. The URL should match exactly what you see when you visit your published site.
+
+Some AI tools require specific transport methods or have particular MCP configuration requirements. Check your AI tool’s documentation for MCP setup instructions.
+
diff --git a/publishing-documentation/publish-a-docs-site/README.md b/publishing-documentation/publish-a-docs-site/README.md
new file mode 100644
index 00000000..67a70b82
--- /dev/null
+++ b/publishing-documentation/publish-a-docs-site/README.md
@@ -0,0 +1,42 @@
+---
+description: Publish your documentation to the internet as a docs site
+icon: globe
+---
+
+# Publish a docs site
+
+Once you’ve finished writing, editing, or importing your content, you can publish your work to the web as a docs site. Your docs will be published on the web and available to your selected audience.
+
+The content on your site comes from [spaces](../../creating-content/content-structure/space.md) in your organization. When you create a new docs site, you can create a new space, or link an existing one.
+
+
GitBook's docs sites homepage.
+
+### Create a docs site
+
+To create a docs site, click the plus **+** icon next to Docs site in the sidebar to launch the docs site wizard.
+
+Give your site a name, choose a starting point for your content, and select whether you want to publish your site now or later.
+
+If you already have content in a space that you would like to use, you can create a docs site directly from that space by opening the space and clicking **Share** in the top-right corner of the window. Then choosing **Publish as a docs site** from the share modal.
+
+### Publish a docs site
+
+By default, your site will be published publicly. You can change your site’s visibility in your [site’s settings](../site-settings.md).
+
+There are three primary options to choose from when publishing your site:
+
+
+
+### Delete or unpublish a docs site
+
+To delete a docs site, you’ll need to open your site’s dashboard, then open [**Site settings**](../site-settings.md#delete-site) from the top-right corner.
+
+### Site editing permissions
+
+Docs sites inherit the editing permissions from the [spaces](../../creating-content/content-structure/space.md) linked to them.
+
+You can view all the permissions set for users with access to the docs site from the permissions modal from the docs site’s **Overview** page. You’ll also see which space the user’s permission was inherited from. If you’d like to change the permission settings, open the space, then click **Share**. Here you can edit the permissions from a modal.
+
+Users with **Administrator** or **Creator** permissions on _any_ space linked to a specific docs site will have full access permissions for the site. This means that they’ll be able to control any of the publishing and customization settings.
+
+Users with **Reviewer**, **Editor**, **Commenter**, or **Reader** permissions on any space linked to a specific site will get read-only permissions. This means they will see the docs site in your organization, but won’t be able to access any of its settings.
diff --git a/publishing-documentation/publish-a-docs-site/public-publishing.md b/publishing-documentation/publish-a-docs-site/public-publishing.md
new file mode 100644
index 00000000..ab11a575
--- /dev/null
+++ b/publishing-documentation/publish-a-docs-site/public-publishing.md
@@ -0,0 +1,51 @@
+---
+description: Publish your docs publicly to the web so that everyone can access them.
+---
+
+# Public publishing
+
+If you created your docs for a public audience, you can publish it on the web. Spaces that you publish on the web can be indexed by search engines and will be available to anyone. If you don’t want your content to be indexed by search engines, you can disable that too — read more about that [below](public-publishing.md#publish-as-public).
+
+However you publish your content, you’ll still retain control over who can _edit_ your content. And only your primary content branch will be published, so any [change requests](../../collaboration/change-requests.md) will remain private until merged.
+
+### Publish as public
+
+To publish your docs publicly on the web head to the docs site you want to publish, click **Publish** button, and choose the **Public** option.
+
+### **Publish without search engine indexing**
+
+By default, your site will be indexed by search engines. You can alternatively choose to disable this — meaning the docs are still available to everyone on the web, but they _won’t_ be indexed by search engines such as Google.
+
+They will still be accessible to anyone with a the link to your documentation. Docs sites that aren’t indexed can be particularly helpful if you want to publish a beta version of your docs, or do large-scale user testing without impacting your SEO with potentially duplicate content.
+
+### Page-level search indexing controls
+
+You can also control search indexing at the individual page level. GitBook provides two types of search indexing controls:
+
+#### Internal search indexing
+
+Controls whether pages are indexed in GitBook's internal search engine and Ask AI feature. This affects:
+
+* Content search within your GitBook space
+* Ask AI's ability to reference the page content
+
+**External search indexing (Web crawlers)**
+
+Controls whether search engines and web crawlers (Google, ChatGPT, etc.) can index your pages. This affects:
+
+* SEO and discoverability through search engines
+* Web crawler access to your content
+
+#### **Hierarchical inheritance behavior**
+
+**Search indexing settings follow a hierarchical inheritance pattern:**
+
+* **Parent page controls**: When you disable search indexing on a parent page, it automatically disables indexing for ALL sub-pages beneath it.
+* **Children cannot override**: Sub-pages cannot re-enable search indexing if their parent page has it disabled.
+* **Cascading effect**: This creates a cascading effect down the entire page hierarchy - disabling indexing on a top-level page will disable it for the entire section.
+
+This hierarchical behavior ensures consistent indexing policies across related content sections and prevents accidental exposure of content that should remain private within a section.
+
+{% hint style="info" %}
+This feature is available on [Premium and Ultimate site plans](https://www.gitbook.com/pricing).
+{% endhint %}
diff --git a/publishing-documentation/publish-a-docs-site/share-links.md b/publishing-documentation/publish-a-docs-site/share-links.md
new file mode 100644
index 00000000..87037ee9
--- /dev/null
+++ b/publishing-documentation/publish-a-docs-site/share-links.md
@@ -0,0 +1,33 @@
+---
+description: Add greater control over who can view your published GitBook documentation.
+---
+
+# Private publishing with share links
+
+{% include "../../.gitbook/includes/premium-and-ultimate-hint.md" %}
+
+You can share you content privately with customers or partners without needing to invite them to your organization by using share links.
+
+### Publish with share links
+
+To publish your docs privately, head to the [docs site’s ](../site-settings.md)settings, click **Audience settings** button, and choose the **Share links** option.
+
+Next, click on **Create link** to create a share link. You can review and name your share links, customize your domain and copy the link.
+
+Once the link is active, a private token is generated within your URL, which is unique to your space. Sharing this link will give non-GitBook users access to your content in read mode only, with an interface that looks like any other published content.
+
+You can generate as many links as you need from **Audience settings**.
+
+{% hint style="info" %}
+You can [revoked](share-links.md#revoke-a-link) and regenerate share links at any time.
+{% endhint %}
+
+### Access and permissions
+
+The content will be accessible to **anyone following the link**. Your team members can access your content from the **Docs sites** section of the sidebar, or by navigating to the space directly.
+
+### Revoke a link
+
+You can disable or regenerate your shareable by revoking it. You can see and revoke any previously generated link by opening the visibility menu and clicking through to link and domain settings.
+
+Once you revoke a link, anyone with that outdated link to your content will no longer have access.
diff --git a/publishing-documentation/search-and-gitbook-assistant.md b/publishing-documentation/search-and-gitbook-assistant.md
new file mode 100644
index 00000000..0bea0a3e
--- /dev/null
+++ b/publishing-documentation/search-and-gitbook-assistant.md
@@ -0,0 +1,60 @@
+---
+description: >-
+ Help your users find the information they need faster with powerful knowledge
+ discovery tools for your published content.
+icon: magnifying-glass
+---
+
+# AI Search
+
+Help your users find the information they need faster with powerful knowledge discovery tools for your published content
+
+### Choose your site’s search experience
+
+GitBook sites offer different search experiences depending on what you want for your users:
+
+* **Keyword search** – A standard search experience based on keywords. Automatically enabled on all sites.
+* **GitBook AI search** – Users get short answers to questions directly from the search box.
+* **GitBook Assistant** – Users get an advanced, interactive chat experience with GitBook’s AI agent. Head to [GitBook Assistant](gitbook-assistant/) to learn more.
+
+To choose your site’s search experience, open your site’s dashboard, navigate to the **Settings** page and choose **AI & MCP** from the menu on the left. Here you can choose your preferred experience.
+
+
Choose the search experience you want in your published docs
+
+{% hint style="warning" %}
+When GitBook Assistant is enabled, AI search is disabled. Standard keyword searches will always provide the results in the search bar no matter which experience you choose.
+{% endhint %}
+
+## Searching published documentation
+
+****Users can open the **Ask or search…** bar by pressing ⌘ + K on Mac or Ctrl + K on PC.
+
+Your users can search for keywords within your docs site and jump quickly to specific pages or page sections across your entire site.
+
+If your docs site has multiple [sections](site-structure/site-sections.md), the search results will contain pages from all of these sections so that you users can jump straight to the page they need.
+
+## GitBook AI search
+
+{% hint style="info" %}
+This feature is available on [Premium and Ultimate site plans](https://www.gitbook.com/pricing).
+{% endhint %}
+
+GitBook AI search offers basic AI-powered answers in the **Search and find…** bar of your site. It’s trained on the content of your docs site, but cannot pull in information from external sources.
+
+### Using GitBook AI search
+
+If you have enabled GitBook AI search from your site’s settings page, your users can access it by asking a question directly in the **Ask or search…** bar at the top of the page.
+
+They can open this by clicking it directly, or by pressing ⌘ + K on a Mac or Ctrl + K on a PC.
+
+As well as a summarized answer, below your users will also see an expandable section that shows the sources that GitBook AI used to create its answer, plus related questions you can click as a follow-up.
+
+{% hint style="warning" %}
+GitBook AI does not work across individual published spaces on different [docs sites](publish-a-docs-site/).
+
+Multi-space search is only available when viewing published spaces that live as [site sections](site-structure/site-sections.md) within the same site.
+{% endhint %}
+
+* Press ⌘ + I on Mac or Ctrl + I on PC
+* Click the **GitBook Assistant** button next to the **Ask or search…** bar
+* Type a question into the **Ask or search…** bar and choose the ‘Ask…’ option at the top of the menu.
diff --git a/publishing-documentation/setting-a-custom-subdirectory/README.md b/publishing-documentation/setting-a-custom-subdirectory/README.md
new file mode 100644
index 00000000..93fc4ec6
--- /dev/null
+++ b/publishing-documentation/setting-a-custom-subdirectory/README.md
@@ -0,0 +1,17 @@
+---
+description: Set a custom subdirectory for your docs sites
+icon: folder-tree
+---
+
+# Setting a custom subdirectory
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+With a custom subdirectory, you can make your docs site accessible at `example.com/docs`. This is different from a [custom domain](../custom-domain.md) which lets you make your docs site accessible at `docs.example.com`.
+
+One reason to do this is so that your docs URL is formatted in a consistent way with your other site URLs. Using a subdirectory may also be beneficial for SEO.
+
+To configure a subdirectory, you'll need to set things up in your website's backend, then finalize the process in your GitBook site settings.
+
+
+
diff --git a/publishing-documentation/setting-a-custom-subdirectory/configuring-a-subdirectory-with-cloudflare.md b/publishing-documentation/setting-a-custom-subdirectory/configuring-a-subdirectory-with-cloudflare.md
new file mode 100644
index 00000000..5d4a6da1
--- /dev/null
+++ b/publishing-documentation/setting-a-custom-subdirectory/configuring-a-subdirectory-with-cloudflare.md
@@ -0,0 +1,71 @@
+---
+description: Host your documentation with a /docs subdirectory using Cloudflare
+icon: cloudflare
+---
+
+# Configuring a subdirectory with Cloudflare
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+{% stepper %}
+{% step %}
+### Configuring your GitBook site
+
+In your GitBook organization, click on your docs site name in the sidebar, then click **Manage site** or open the **Settings** tab. Open the **Domain and redirects** section and under ‘Subdirectory’, click **Set up a subdirectory**.
+
+Enter the URL where you would like to host your docs. Then specify the subdirectory for docs access, e.g. `tomatopy.pizza/docs`, and click **Configure**.
+
+Under **Additional configuration**, you will now see a proxy URL. You'll use this in the next step when configuring your Cloudflare worker. Copy it to your clipboard.
+{% endstep %}
+
+{% step %}
+### Create your Cloudflare worker
+
+Sign into your Cloudflare account and navigate to **Workers & Pages**
+
+Click the **Create** button.
+
+On the ‘Create an application’ screen, click the **Hello world** button in the ‘Start from a template’ card.
+
+Give the worker a more descriptive name, like `mydocs-subpath-proxy`. Once you finish renaming the worker, click **Deploy**.
+{% endstep %}
+
+{% step %}
+## Configure your custom domain
+
+Your worker will get a default URL that you can use. To configure your custom domain instead (such as `tomatopy.pizza`), click **Settings.** Then, in the ‘Domains & Routes’ section, click **+ Add**.
+
+In the ‘Domains & Routes’ tray that opens, click **Custom domain**, then enter your custom domain in the textbox that follows. When you specify the custom domain, _do not_ include the subdirectory. For example, `tomatopy.pizza` is correct, while `tomatopy.pizza/docs` is not.
+{% endstep %}
+
+{% step %}
+### Update the worker code
+
+When the worker is finished deploying, click **Edit code**, or click **Continue to project**, and then the **Edit code** button in the upper right.
+
+In the code editor that opens, replace the sample code with the following snippet:
+
+{% code lineNumbers="true" %}
+```javascript
+export default {
+ fetch(request) {
+ const SUBDIRECTORY = '/docs';
+ const url = new URL(request.url);
+ const target = "" + url.pathname.slice(SUBDIRECTORY.length);
+ const proxy = new URL(
+ target.endsWith('/') ? target.slice(0, -1) : target
+ )
+ proxy.search = url.search;
+ return fetch(new Request(proxy, request));
+ }
+};
+```
+{% endcode %}
+
+{% hint style="info" %}
+Be sure to update the URL on line 5 with the proxy URL you got from GitBook in the first step.
+{% endhint %}
+
+Once that’s done, click **Deploy**. This process may take a few moments. Once it’s complete, when visiting the URL, you should see your docs site!
+{% endstep %}
+{% endstepper %}
diff --git a/publishing-documentation/setting-a-custom-subdirectory/configuring-a-subdirectory-with-vercel.md b/publishing-documentation/setting-a-custom-subdirectory/configuring-a-subdirectory-with-vercel.md
new file mode 100644
index 00000000..e2ada8f4
--- /dev/null
+++ b/publishing-documentation/setting-a-custom-subdirectory/configuring-a-subdirectory-with-vercel.md
@@ -0,0 +1,49 @@
+---
+description: Host your documentation with a /docs subdirectory using Vercel
+icon: triangle
+---
+
+# Configuring a subdirectory with Vercel
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+{% stepper %}
+{% step %}
+### Configuring your GitBook site
+
+In your GitBook instance, click on your docs site name in the sidebar, then **Manage site**, then **Domain and redirects**. Under ‘Subdirectory’, click **Set up a subdirectory**.
+
+Enter the URL where you would like to host your docs. Then specify the subdirectory for docs access, e.g. `tomatopy.pizza/docs`, and click **Configure**.
+
+Under **Additional configuration**, you will now see a proxy URL. You'll use this in the next step when configuring your Vercel settings. Copy it to your clipboard.
+{% endstep %}
+
+{% step %}
+### Update your vercel.json
+
+In your Vercel app, open your `vercel.json`file (or create one in the root directory if you don't already have one). Then, add the following:
+
+```json
+{
+ "rewrites": [
+ {
+ "source": "/docs",
+ "destination": ""
+ },
+ {
+ "source": "/docs/:match*",
+ "destination": "/:match*"
+ }
+ ]
+}
+```
+
+_Be sure to update the URL_ on line 5 with the proxy URL you got from GitBook in the first step.
+{% endstep %}
+
+{% step %}
+### Re-deploy your app and try it out!
+
+Re-deploy your Vercel app with the update configuration. This may take a few moments. Now, when visiting the URL, you should see your docs site!
+{% endstep %}
+{% endstepper %}
diff --git a/publishing-documentation/site-redirects.md b/publishing-documentation/site-redirects.md
new file mode 100644
index 00000000..c8c9c5b5
--- /dev/null
+++ b/publishing-documentation/site-redirects.md
@@ -0,0 +1,40 @@
+---
+description: Set up site redirects to route traffic to content anywhere on your site.
+icon: diamond-turn-right
+---
+
+# Site redirects
+
+{% include "../.gitbook/includes/premium-and-ultimate-hint.md" %}
+
+
Site redirects are useful when migrating documentation or restructuring content to avoid broken links, which can impact SEO.
+
+Redirects are commonly used when you are migrating your documentation from one provider to another — like when you just moved docs to GitBook. Broken links can impact SEO so we recommend setting up redirects where needed.
+
+In addition to [automatic redirects created by GitBook](site-redirects.md#about-automatic-redirects), you can create a redirect from any path in your site’s domain.
+
+## Managing redirects on your site
+
+To get started, view your site’s dashboard in GitBook and open the **Settings** tab, then click **Domain & redirects**.
+
+### Creating redirects
+
+Click **Add redirect** to begin. Fill in the source path — i.e. the URL slug that you wish to redirect somewhere else — and the destination content you wish to link to. You can pick any [section](site-structure/site-sections.md), [variant](site-structure/variants.md), or [page](../creating-content/content-structure/page.md) on to your site. Click **Add** to create the redirect.
+
+If you want to add another redirect to the same page, you can toggle the **Add another redirect** option on before you hit **Add**. When you add your redirect, the modal will remain open with the destination content set to the previous selection so you can add another URL slug immediately.
+
+### Editing redirects
+
+To edit a redirect, press the **Edit** icon next to it in the list. Update the redirect and hit **Save**.
+
+To delete a redirect, press the **Delete redirect** button and confirm.
+
+## About automatic redirects
+
+Whenever pages are moved or renamed, their canonical URL changes with them. In order to keep your content accessible, GitBook automatically creates a [HTTP 307](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/307) redirect from the old URL to the new one.
+
+Every time a URL is loaded, GitBook resolves it through the following steps:
+
+1. Site content is resolved to its canonical URL by following any of the automatically created redirects.
+2. If the URL cannot be resolved, the URL is checked against [space-level redirects](../getting-started/git-sync/content-configuration.md#redirects), defined in your repository's `.gitbook.yaml` file.
+3. Finally, the URL is checked against site-level redirects, created via [the process above](site-redirects.md#creating-redirects).
diff --git a/publishing-documentation/site-settings.md b/publishing-documentation/site-settings.md
new file mode 100644
index 00000000..6d499154
--- /dev/null
+++ b/publishing-documentation/site-settings.md
@@ -0,0 +1,144 @@
+---
+description: Customize and edit settings across your published site
+icon: gear
+---
+
+# Site settings
+
+{% include "../.gitbook/includes/customization-premium-and-ultimate-hint.md" %}
+
+
Update the settings for your published documentation.
+
+### General
+
+
+
+Site title
+
+Change the name of your site, if you don't have a custom logo this is the name that your site visitors will see.
+
+
+
+
+
+Social preview
+
+Here, you can upload a custom social preview image for your site. This will set the site’s `og:image` to your uploaded image, and it’ll show when the site’s link is shared to any platform or product that supports OpenGraph images, such as Slack or X.
+
+If you don’t add a social preview, GitBook will automatically generate one using your theme color, page title and description.
+
+If your site has multiple [site sections](site-structure/site-sections.md), you can use the drop-down menu in this modal to add a custom social preview image for each one, or for your entire site.
+
+
+
+
+
+Unpublish site
+
+Unpublish your site, but keep its settings and customizations. You can publish your site again at any time.
+
+
+
+
+
+Delete site
+
+Unpublish and remove your site from the **Docs site** section in the GitBook app.
+
+**Note:** Deleting a site is a permanent action and cannot be undone. Any settings and customizations will be lost, but your content will remain in its [space](../creating-content/content-structure/space.md).
+
+
+
+### Audience
+
+
+
+Audience
+
+Choose who sees your published content. See [publish-a-docs-site](publish-a-docs-site/ "mention") for more info.
+
+
+
+
+
+Adaptive content Ultimate
+
+Turn on adaptive content for your site pages, variants, and sections. [Adaptive content](adaptive-content/) lets you hide or show content for different visitors, depending on their permissions.
+
+Your visitor token signing key will also be displayed here.
+
+
+
+### Domain and URL
+
+
+
+Custom domain
+
+Configure a custom domain to unify your site with your own branding. See [custom-domain.md](custom-domain.md "mention") for more info.
+
+
+
+
+
+GitBook Subdirectory
+
+Publish your content on a subdirectory (e.g. `yourcompany.com/docs`). See [#gitbook-subdirectory](site-settings.md#gitbook-subdirectory "mention") for more info
+
+
+
+### Redirects
+
+{% content-ref url="site-redirects.md" %}
+[site-redirects.md](site-redirects.md)
+{% endcontent-ref %}
+
+### Features
+
+
+
+PDF export Premium & Ultimate
+
+Let your visitors to export your GitBook as PDF. See [pdf-export.md](../collaboration/pdf-export.md "mention") for more info.
+
+
+
+
+
+Page ratings Premium & Ultimate
+
+Choose whether or not visitors to your published content can leave a rating on each page to let you know how they feel about it. They’ll be able to choose a sad, neutral, or happy face.
+
+You can review the results of these ratings by opening the [**Insights**](insights.md) section of your docs site dashboard and selecting the [**Content scores**](insights.md#content-scores) tab.
+
+
+
+### AI & MCP
+
+
+
+Choose the AI experience Premium & Ultimate
+
+Let your site visitors ask GitBook anything with AI search or the GitBook assistant. See [search-and-gitbook-assistant.md](search-and-gitbook-assistant.md "mention") for more info.
+
+
+
+
+
+Extend it with MCP connectors Ultimate
+
+Configure MCP servers that the AI assistant can use when answering user questions inside your docs. See [#how-do-i-use-gitbook-ai](search-and-gitbook-assistant.md#how-do-i-use-gitbook-ai "mention") for more info.
+
+
+
+### Structure
+
+{% content-ref url="site-structure/" %}
+[site-structure](site-structure/)
+{% endcontent-ref %}
+
+### Plan
+
+{% content-ref url="../account-management/plans/" %}
+[plans](../account-management/plans/)
+{% endcontent-ref %}
diff --git a/publishing-documentation/site-structure/README.md b/publishing-documentation/site-structure/README.md
new file mode 100644
index 00000000..177f8bdc
--- /dev/null
+++ b/publishing-documentation/site-structure/README.md
@@ -0,0 +1,70 @@
+---
+description: Add structure to your published documentation using site sections and variants
+icon: window-restore
+---
+
+# Site structure
+
+The content on your site comes from [spaces](../../creating-content/content-structure/space.md) in your organization. You can link one or multiple spaces. GitBook will publish each one and handle the navigation between spaces.
+
+## Content types
+
+Linked spaces can serve as one of two different content types, which determine how GitBook treats them in relation to each other and shows them to visitors.
+
+
Cover image (dark)
Cover image
Content variants
Publish multiple versions of the same content — ideal for localization, versioning, and more.
+
+## Managing your site structure
+
+From your docs site’s dashboard, open the **Settings** tab in the site header, then click **Structure**. Here you can see all the content of your site, divided into sections and variants.
+
+Your site starts out with a single section with your site's name and a single variant with the space you linked during your site's set-up.
+
+
The structure of a published docs site.
+
+### Linking a space to your docs site
+
+To add a [site section](site-sections.md), click the **Add section** button underneath the table and choose a space to link as a section. The new section is then added to the table and will be available to visitors as a tab at the top of your site.
+
+To add a [variant](variants.md), click the **Add variant** button in the section you’d like to add to, then choose a space to link. The new variant is then added to the list of variants within the chosen section and will be available to visitors in the variant dropdown on your site.
+
+When you add a space — as a variant or a section — a name and slug will be generated based on the space’s title.
+
+### Changing sections or variants
+
+
Update a site section or variant.
+
+You can change the name and slug of each of sections and variants by clicking the **Edit** button in the table row of the item you’d like to edit. This will open a modal. Edit the field(s) you’d like to change, then click the **Save** button to save.
+
+{% hint style="info" %}
+Changing a linked space's slug will change the space's canonical URL. GitBook will create an automatic redirect from the old URL to the new one. You can also [manually create redirects](../site-redirects.md).
+{% endhint %}
+
+To replace a section or variant, first delete it by clicking its **Edit** button, then click the **Delete** button in the lower left of the modal. Once the item is deleted, click the **Add section** or **Add variant** button to add it again.
+
+### Reordering sections or variants
+
+Your site displays sections and variants in the order that they appear in your **Site structure** table. They can be reordered by grabbing the **Drag handle** and moving it up or down. The changed order will be reflected on your site immediately.
+
+You can also use the keyboard to select and move content. Select a section or variant with the space bar, then use the arrow keys to move it up or down. Hit the space bar again to confirm the new position.
+
+### Setting default content
+
+If you have multiple sections in your site, one section will be marked as **Default**. This section is shown when visitors arrive on your site, and is served from your site’s root URL. Other sections each have a slug that is appended to the root URL.
+
+If you have multiple variants within a section, one variant will be marked as the default. Like sections, the default variant is shown when visitors arrive on your site, or when they visit a section. Other variants each have a slug that’s appended to the section’s URL.
+
+To set a space as default, click on the **Actions menu** in the space’s table row and then click **Set as default**.
+
+{% hint style="info" %}
+Setting a space as default removes its slug field, as it will be served from the section root instead. GitBooks redirects the space’s slug to the appropriate path, to ensure visitors keep seeing your content.
+{% endhint %}
+
+### Remove content from a site
+
+To remove the content of a space from a site, open the **Settings** tab from your docs site dashboard, then click **Structure** to find the content you want to remove.
+
+Open the **Actions menu** for the space you want to remove and choose **Remove**.
+
+{% hint style="success" %}
+Removing a space from your site will remove it from the published site, but **will not delete the space or the content within it**.
+{% endhint %}
diff --git a/publishing-documentation/site-structure/site-sections.md b/publishing-documentation/site-structure/site-sections.md
new file mode 100644
index 00000000..65dd0df2
--- /dev/null
+++ b/publishing-documentation/site-structure/site-sections.md
@@ -0,0 +1,73 @@
+---
+description: >-
+ Add multiple products to your site as site sections and create a content hub
+ with tabs to access all your content
+---
+
+# Site sections
+
+{% include "../../.gitbook/includes/ultimate-hint.md" %}
+
+
Example of a GitBook site with site sections
+
+With site sections, you can centralize all your documentation and create a seamless experience for your users.
+
+Site sections are perfect for organizing your documentation — whether you’re managing separate products, or catering to both end-users and developers with content tailored to each.
+
+You can also [group site sections together](site-sections.md#create-a-site-section-group). Doing so will create a drop-down menu in your navigation bar — ideal for adding hierarchy to your site sections.
+
+{% hint style="info" %}
+### Sections or variants?
+
+Each site section is a space in GitBook. You can create site sections from any space you like, but we recommend you use sections as semantically different parts of your docs.
+
+If you want to add variations of the same content — such as localizations or historical versions of the same product — consider using [content variants](variants.md) instead.
+{% endhint %}
+
+### Adding a section to your docs site
+
+From your docs site’s dashboard, open the **Settings** tab in the site header, then click **Structure**. Here you can see all the content of your site.
+
+To add a site section, click the **New section** button underneath the table and choose a space to link as a section. The new section is then added to the table and will be available to visitors as a tab at the top of your site.
+
+
Add structure to your docs with site sections.
+
+### Create a site section group
+
+You can group site sections together under a single heading. Site section groups will appear as a drop-down in your site’s nav. Site sections in a group can also include an optional description, which appears below the section title in the drop-down menu.
+
+To create a group, click the arrow next to the **New section** button and choose **New section group**. Give your new group a name, then click **Add section** in the modal to add sections to your group. You can add existing sections of your site to the new group, or select another space you want to add using the menu.
+
+### Editing a section
+
+You can change the name, icon and slug of each of your sections by tapping the **Edit** button in the table row of the section you’d like to edit. This will open a modal. Edit the field(s) you’d like to change, then click the **Save** button. You can also delete the variant by clicking the **Delete variant** button in the lower left.
+
+{% hint style="info" %}
+Changing a section’s slug will change its canonical URL. GitBook will create an automatic redirect from the old URL to the new one. You can also [manually create redirects](../site-redirects.md).
+{% endhint %}
+
+Site sections within a group can also optionally display a description, which will appear in the drop-down menu of your site’s nav bar when the section group is hovered. See the image at the top of this page to see an example of how this can look in your published documentation.
+
+### Reordering sections
+
+Your site displays sections in the order that they appear in your Site structure table. Sections can be reordered by grabbing the **Drag handle** and moving it up or down. All the spaces within that section will be moved with it. The changed order will be reflected on your site immediately.
+
+You can also use the keyboard to select and move content: select a section with the space bar, then use the arrow keys to move it up or down. Hit the space bar again to confirm the new position.
+
+### Setting a default section
+
+If you have multiple sections in your site, one section will be marked as the default. This section is shown when visitors arrive on your site, and is served from your site’s root URL. Other sections each have a slug that is appended to the root URL.
+
+To set a section as default, click on the **Actions menu** in the section's table row and then click **Set as default**.
+
+### Remove a section
+
+To remove a section from a site, click the **Settings** button from your docs site dashboard, then click **Structure** to find the content you want to remove. Click the **Edit** button next to the section you want to remove, then click the **Delete** button in the lower left of the modal. This will remove the section, along with all the variants within it, from the published site. It will not delete the spaces itself, or the content within them.
+
+To remove a section from a site, open the **Settings** tab from your docs site dashboard, then click **Structure** to find the content you want to remove.
+
+Open the **Actions menu** for the space you want to remove and choose **Remove**.
+
+{% hint style="success" %}
+Removing a section from your site will remove it — and all variants within it — from the published site, but **will not delete any of the spaces or the content within them**.
+{% endhint %}
diff --git a/publishing-documentation/site-structure/variants.md b/publishing-documentation/site-structure/variants.md
new file mode 100644
index 00000000..d40e1d13
--- /dev/null
+++ b/publishing-documentation/site-structure/variants.md
@@ -0,0 +1,65 @@
+---
+description: >-
+ Publish documentation for multiple product versions or languages in a single
+ site
+---
+
+# Content variants
+
+You can publish multiple versions of the same documentation as part of a single docs site. These variants will be available to the end users via the space switcher in the top-left corner of the published site.
+
+
+
+### Add multiple languages or versions
+
+A site with multiple variants is useful if you need to group together the content of your spaces — such as if you’re documenting multiple versions of an API (v1, v2, v3, etc.), or documenting your content in different languages.
+
+{% hint style="info" %}
+The spaces you link can contain any content, but it’s recommended to use variants as _variations of the same content_. If the spaces you link are semantically different from each other, consider adding them as [site sections](site-sections.md) instead.
+{% endhint %}
+
+When adding a translation or multiple languages as a variant, it’s best practice to set the language of your variant to give your users the best experience when navigating your docs.
+
+Adding multiple variants with languages set will move the language picker to the upper right, giving a cleaner, more direct experience from the default variant picker.
+
+### Adding a variant to your docs site
+
+From your docs site’s dashboard, open the **Settings** tab in the site header, then click **Structure**. Here you can see all the content of your site.
+
+To add a variant, click the **Add variant** button in the section you'd like to add to, then choose a space to link. The new variant is then added to the list of variants within the chosen section and will be available to visitors in the variant dropdown on your site.
+
+### Changing a variant
+
+You can change the name and slug of each of your variants by clicking the **Edit** button in the table row of the variant you’d like to edit. This will open a modal. Edit the field(s) you'd like to change, then click the **Save** button to save. You can also delete the variant by clicking the **Delete variant** button in the lower left.
+
+{% hint style="info" %}
+Changing a linked space's slug will change the space's canonical URL. GitBook will create an automatic redirect from the old URL to the new one. You can also [manually create redirects](../site-redirects.md).
+{% endhint %}
+
+To replace a variant’s linked space with a different space, first delete it by clicking its **Edit** button, then click the **Delete** button in the lower left of the modal. Once the variant is deleted, click the **Add variant** button to add the new space.
+
+### Reordering variants
+
+Your site displays variants in the order that they appear in your **Site structure** table. Variants can be reordered by grabbing the **Drag handle** and moving it up or down. The changed order will be reflected on your site immediately.
+
+You can also use the keyboard to select and move content: select a section or variant with the space bar, then use the arrow keys to move it up or down. Hit the space bar again to confirm the new position.
+
+### Setting a default variant
+
+If you have multiple variants within a section, one variant will be marked as the default. This variant is shown when visitors arrive on your site (or when they visit a section). Other variants each have a slug that is appended to the site's URL.
+
+To set a variant as default, click on the **Actions menu** in the variant’s table row and then click **Set as default**.
+
+{% hint style="info" %}
+Setting a variant as default removes its slug field, as it will be served from the section root instead. GitBook will redirect the variant's slug to the appropriate path, to ensure visitors keep seeing your content.
+{% endhint %}
+
+### Remove a variant from a site
+
+To remove a variant from a site, open the **Settings** tab from your docs site dashboard, then click **Structure** to find the content you want to remove.
+
+Open the **Actions menu** for the variant you want to remove and choose **Remove**.
+
+{% hint style="success" %}
+Removing a variant from your site will remove it from the published site, but **will not delete the space or the content within it**.
+{% endhint %}
diff --git a/publishing/custom-domain/README.md b/publishing/custom-domain/README.md
deleted file mode 100644
index e75a51fa..00000000
--- a/publishing/custom-domain/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-description: >-
- Learn how to set a custom domain for your GitBook organization, collection, or
- space.
----
-
-# Set a custom domain
-
-By default, your spaces and collections are accessible on a `[something].gitbook.io` domain. However, you can customize this by setting a custom domain, meaning your audience will be able to access your documentation on a domain that makes sense for your organization.
-
-If you have any trouble while following the steps in this section, please first [review our troubleshooting information](troubleshooting.md), and then [contact support](../../help/support.md) if you’re still not sure what to do next.
-
-{% hint style="info" %}
-**Permissions**
-
-Custom domains can be set at the organization level by users with admin rights, and can be set at the collection or space level by users with creator or admin rights.
-{% endhint %}
-
-### Learn more about:
-
-
diff --git a/publishing/custom-domain/choose.md b/publishing/custom-domain/choose.md
deleted file mode 100644
index aa7d13be..00000000
--- a/publishing/custom-domain/choose.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Choosing a subdomain
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [**Choosing a subdomain**](choose.md) **(you are here)**
-2. [Deciding where to set the custom domain](location.md)
-3. [Initiating the custom domain setup](initiate/) (at the [organization](initiate/organization-level-custom-domain.md), [collection](initiate/collection-level-custom-domain.md), or [space](initiate/space-level-custom-domain.md) level)
-4. [Configuring DNS](configure-dns.md)
-5. [Confirming the custom domain setup](finalize.md)
- {% endhint %}
-
-_Only_ subdomains can be used to serve your GitBook documentation. It’s not possible to use an apex domain.
-
-Here are some examples of what you could and could not choose — just replace `example.com` with your own domain:
-
-| Domain type | Example | Supported? |
-| ---------------- | ------------------------------------------------------------------------------------------------------------- | :--------: |
-| Apex domain | `example.com` | ❌ |
-| `www` subdomain | `www.example.com` | ✅ |
-| Custom subdomain |
docs.example.com
help.example.com anything.example.com
| ✅ |
-
-Once you have chosen your custom domain, you’re ready to move onto the next step: [deciding where to set the custom domain](location.md).
diff --git a/publishing/custom-domain/configure-dns.md b/publishing/custom-domain/configure-dns.md
deleted file mode 100644
index 2f9a0d8b..00000000
--- a/publishing/custom-domain/configure-dns.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Configuring DNS
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](choose.md)
-2. [Deciding where to set the custom domain](location.md)
-3. [Initiating the custom domain setup](initiate/) (at the [organization](initiate/organization-level-custom-domain.md), [collection](initiate/collection-level-custom-domain.md), or [space](initiate/space-level-custom-domain.md) level)
-4. [**Configuring DNS**](configure-dns.md) **(you are here)**
-5. [Confirming the custom domain setup](finalize.md)
- {% endhint %}
-
-Configuring DNS happens _outside_ of GitBook, at the DNS provider you are using for your domain.
-
-**This step is super important** because the correct DNS configurations are what allow us to connect the subdomain to your space, collection, or organization.
-
-There are three parts to this step:
-
-1. [Configure a CNAME record](configure-dns.md#configure-a-cname-record)
-2. [Check for a CAA record](configure-dns.md#check-for-a-caa-record)
-3. [Wait for the changes to take effect](configure-dns.md#wait-for-the-changes-to-take-effect)
-
-## Configure a CNAME record
-
-{% hint style="info" %}
-The short answer: point your subdomain to GitBook via the CNAME record using the name and value that you copied to your clipboard in the previous step.
-{% endhint %}
-
-The names of the fields and what to actually enter to configure the record may differ between DNS control panels, but we’ve covered the most common options here. If you’re in any doubt, check with your DNS provider.
-
-- The **type** is the kind of DNS record that you want to create. Here, you need to choose **CNAME**.
-- The **name** or **DNS entry** is where you enter your subdomain. You might need to enter it in full (e.g. **docs.example.com**) or you might just need to enter the part before your apex domain (e.g. **docs**). If you’re not sure which to use, check with your DNS provider.
-- The **target** or **value** or **destination** is where the subdomain should be pointed.
-
-You might also see a field named **TTL**, which stands for Time To Live. It’s the number of seconds that the DNS record can be cached for. If you’re not sure what to set, look at the TTL for your existing DNS records. You could set the same number. If you’re still not sure, we suggest setting 43200 seconds (12 hours) or 86400 seconds (24 hours).
-
-Here’s an example of how a correct configuration looks in Cloudflare’s control panel:
-
-
-
-{% hint style="warning" %}
-**Note:** a CNAME record cannot co-exist with another record for the same name. If you already have an A record, AAAA record, TXT record, or any other type of record for your chosen subdomain, you would need to remove those first, _before_ adding the CNAME record.
-{% endhint %}
-
-### Are you using Cloudflare?
-
-If you are configuring DNS in Cloudflare’s control panel, please ensure that Cloudflare’s proxying (the orange cloud, also called "Proxy status" in your domain settings) is **disabled**. This is for two reasons:
-
-1. This option obfuscates the DNS target for your domain to the public, preventing GitBook from properly running routine checks on your custom domain.
-2. Your custom domain will already benefit from Cloudflare’s CDN and a Google Trust Services SSL certificate on our end.
-
-Again, please **turn off Cloudflare proxying** to ensure that your documentation is served without issues and can be monitored by GitBook.
-
-## Check for a CAA record
-
-{% hint style="info" %}
-The short answer: either don’t have a CAA record, or have one that explicitly allows Google Trust Services.
-{% endhint %}
-
-CAA records enable you to specify who can issue an SSL certificate for the domains that you own. We use Google Trust Services to issue an SSL certificate for your custom domain, so this needs to be allowed. There are two ways to do this.
-
-1. Have no CAA record. Without a CAA record, there are no limitations on which SSL providers are allowed to issue an SSL certificate for your domain.
-2. Have a CAA record that explicitly allows Google Trust Services. If a CAA record exists, any providers that are not explicitly allowed will be blocked. The following is the value that would need to be included in a CAA record to explicitly allow Google Trust Services:
-
-```
-0 issue "pki.goog"
-```
-
-## Wait for the changes to take effect
-
-{% hint style="info" %}
-The short answer: you might need to wait 1-48 hours for the DNS changes to take effect before moving onto the next step.
-{% endhint %}
-
-Remember the TTL (Time To Live) field we mentioned earlier? DNS records are cached for a period of time — which is usually a very good thing for performance reasons, because they typically don’t change very often. When they _do_ change, there is a period of time (the TTL value) where DNS cache servers need their cache to expire before they will check for any changes and behave accordingly.
-
-In most cases, it’s best to allow at least an hour before moving onto the next and final step. Sometimes it could all update a bit more quickly, or it could take longer. It’s rare for this to take longer than 48 hours.
-
-Want to check how this process, known as _propagation_, is progressing? You could use a DNS lookup tool, such as [WhatsMyDNS](https://www.whatsmydns.net/). Enter your full subdomain, select CNAME from the dropdown list, and press the Search button. DNS cache servers around the world will respond to let you know what their cached result is. You’ll want to periodically check these results until the vast majority respond with your assigned CNAME value.
-
-Once DNS propagation has completed, you can move onto the last step: [confirming the custom domain setup](finalize.md).
diff --git a/publishing/custom-domain/finalize.md b/publishing/custom-domain/finalize.md
deleted file mode 100644
index 982c4d6a..00000000
--- a/publishing/custom-domain/finalize.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Confirming the custom domain setup
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](choose.md)
-2. [Deciding where to set the custom domain](location.md)
-3. [Initiating the custom domain setup](initiate/) (at the [organization](initiate/organization-level-custom-domain.md), [collection](initiate/collection-level-custom-domain.md), or [space](initiate/space-level-custom-domain.md) level)
-4. [Configuring DNS](configure-dns.md)
-5. [**Confirming the custom domain setup**](finalize.md) **(you are here)**
- {% endhint %}
-
-Once your CNAME record has taken effect, or has _propagated_, you’re ready to confirm the setup in GitBook. As a reminder, this could take anywhere from a few minutes to 48 hours.
-
-If you’re setting an organization-level custom domain, go back into the organization settings page, and click the **Edit domain** button in the Publishing section.
-
-If you’re setting a collection- or space-level custom domain, go back into the Share modal for that collection or space. From either the **Publish to the web** or **Share to an audience** tab (depending on how it has been published) click the **Edit domain** button.
-
-If our setup process is still in progress, you’ll see the same options as you saw before. Click on the **Next: Configure DNS** button and then the **Ready: Go Live** button to get to the final screen.
-
-The first thing we’ll do is check to see if the correct DNS record has taken effect. Once we’ve been able to detect this, you’ll see an update on the screen:
-
-
-
-
-
-
-
-Next, we’ll configure an SSL certificate for the custom domain automatically. This part of the process might take a few minutes. Once it has been completed successfully, you’ll see a success message:
-
-
-
-
-
-
-
-Visitors to your documentation can now use your custom domain to access it. 🎉
-
-If you ever change your mind, you can always go back to the organization settings page or to the Share modal for a collection or space to edit or remove the custom domain.
-
-If you follow the steps on this page and you don’t see the success message, some more time might still be needed for the CNAME record to propagate. Try allowing about another hour before coming back to try it again, or review our [troubleshooting](troubleshooting.md) information if you still have trouble. Remember that it _can_ in some cases take up to 48 hours for the change to fully take effect.
diff --git a/publishing/custom-domain/initiate/README.md b/publishing/custom-domain/initiate/README.md
deleted file mode 100644
index b4f32f80..00000000
--- a/publishing/custom-domain/initiate/README.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Initiating the custom domain setup
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](../choose.md)
-2. [Deciding where to set the custom domain](../location.md)
-3. [**Initiating the custom domain setup**](./) **(at the** [**organization**](organization-level-custom-domain.md)**,** [**collection**](collection-level-custom-domain.md)**, or** [**space**](space-level-custom-domain.md) **level) (you are here)**
-4. [Configuring DNS](../configure-dns.md)
-5. [Confirming the custom domain setup](../finalize.md)
-{% endhint %}
-
-Depending on the option you chose in the previous step, please follow the steps on one of the following pages:
-
-* Set an [organization-level custom domain](organization-level-custom-domain.md)
-* Set a [collection-level custom domain](collection-level-custom-domain.md)
-* Set a [space-level custom domain](space-level-custom-domain.md)
diff --git a/publishing/custom-domain/initiate/collection-level-custom-domain.md b/publishing/custom-domain/initiate/collection-level-custom-domain.md
deleted file mode 100644
index 8d52e6e3..00000000
--- a/publishing/custom-domain/initiate/collection-level-custom-domain.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Collection-level custom domain
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](../choose.md)
-2. [Deciding where to set the custom domain](../location.md)
-3. [**Initiating the custom domain setup**](./) **(at the** [**organization**](organization-level-custom-domain.md)**,** [**collection**](collection-level-custom-domain.md)**, or** [**space**](space-level-custom-domain.md) **level) (you are here)**
-4. [Configuring DNS](../configure-dns.md)
-5. [Confirming the custom domain setup](../finalize.md)
- {% endhint %}
-
-{% hint style="warning" %}
-The custom domain will be used as-is for the default space in the collection. Other spaces in the collection will have a URL in this format: `[yourcustomdomain]/v/[spaceURL]`.
-{% endhint %}
-
-You’ll find the options for setting a custom domain for a collection within the collection’s Share modal. To get there, click on the name of the collection in the sidebar, and then click on the **Share** button near the top-right corner. It will look something like this:
-
-
-
-
Click the button to open the share modal
-
-
-
-First, your collection needs to be published. Any setting other than unpublished will work — **public**, **unlisted**, **share link**, or **visitor authentication**. (Depending on the plan you have chosen, it might be that only _some_ of these publishing options are available to you.)
-
-Once you have published your collection on either the **Publish to the web** or the **Share to an audience tab**, you’ll see a section titled **Customize URL**. Click on the **Connect a domain** button:
-
-
-
-
The share modal
-
-
-
-Now, enter the custom domain you’d like to set, and then click the **Next: Configure DNS** button:
-
-
-
-
Connect a custom domain
-
-
-
-We’ll then provide the name and value to use in the next step when you create your CNAME DNS record. You can copy the name or value to your clipboard by clicking on the icon on the right-hand side of each field.
-
-
-
-
The CNAME value for your custom domain
-
-
-
-The value for the CNAME record will be in the format `[something]-hosting.gitbook.io`, where that `[something]` will be **unique to you**. Make sure to use the value displayed to you in the GitBook app, and _not_ the value in the screenshot above! 🙂
-
-Now, you’re ready to move onto the next step: [configuring DNS](../configure-dns.md).
diff --git a/publishing/custom-domain/initiate/organization-level-custom-domain.md b/publishing/custom-domain/initiate/organization-level-custom-domain.md
deleted file mode 100644
index 2ee46968..00000000
--- a/publishing/custom-domain/initiate/organization-level-custom-domain.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Organization-level custom domain
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](../choose.md)
-2. [Deciding where to set the custom domain](../location.md)
-3. [**Initiating the custom domain setup**](./) **(at the** [**organization**](organization-level-custom-domain.md)**,** [**collection**](collection-level-custom-domain.md)**, or** [**space**](space-level-custom-domain.md) **level) (you are here)**
-4. [Configuring DNS](../configure-dns.md)
-5. [Confirming the custom domain setup](../finalize.md)
- {% endhint %}
-
-{% hint style="warning" %}
-Before you’ll be able to set a custom domain for your organization, **at least one space owned by the organization will need to be published**. If all of the spaces are unpublished, you won’t see the publishing section on the organization settings page.
-{% endhint %}
-
-You’ll find the options for setting a custom domain for an organization within the organization settings page. To get there, open the settings menu. This is located at the bottom of the sidebar — click on the cog  icon to open the menu. Then, click on the **\[Org Name] Settings** link. It will look something like this:
-
-
Accessing the organization settings
-
-On the next page, in the **Publishing** section, next to **Custom Domain**, click the **Connect a domain** button.
-
-
-
-
An organization’s settings page with the custom domain section highlighted
-
-
-
-This will open up a window where you can enter the custom domain, and then click the **Next: Configure DNS** button:
-
-
-
-
Connect a custom domain
-
-
-
-We’ll then provide the name and value to use in the next step when you create your CNAME DNS record. You can copy the name or value to your clipboard by clicking on the icon on the right-hand side of each field.
-
-
-
-
The name and value for the CNAME record
-
-
-
-The value for the CNAME record will be in the format `[something]-hosting.gitbook.io`, where that `[something]` will be **unique to you**. Make sure to use the value displayed to you in the GitBook app, and _not_ the value in the screenshot above! 🙂
-
-Now, you’re ready to move onto the next step: [configuring DNS](../configure-dns.md).
diff --git a/publishing/custom-domain/initiate/space-level-custom-domain.md b/publishing/custom-domain/initiate/space-level-custom-domain.md
deleted file mode 100644
index 0fbc4cee..00000000
--- a/publishing/custom-domain/initiate/space-level-custom-domain.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Space-level custom domain
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](../choose.md)
-2. [Deciding where to set the custom domain](../location.md)
-3. [**Initiating the custom domain setup**](./) **(at the** [**organization**](organization-level-custom-domain.md)**,** [**collection**](collection-level-custom-domain.md)**, or** [**space**](space-level-custom-domain.md) **level) (you are here)**
-4. [Configuring DNS](../configure-dns.md)
-5. [Confirming the custom domain setup](../finalize.md)
- {% endhint %}
-
-You’ll find the options for setting a custom domain for a space within the space’s Share modal. To get there, click on the name of the space in the sidebar, and then click on the **Share** button near the top-right corner. It will look something like this:
-
-
-
-
Click the button to open the share modal
-
-
-
-First, your space needs to be published. Any setting other than unpublished will work — **public**, **unlisted**, **share link**, or **visitor authentication**. (Depending on the plan you have chosen, it might be that only _some_ of these publishing options are available to you.)
-
-Once you have published your space on either the **Publish to the web** or the **Share to an audience tab**, you’ll see a section titled **Customize URL**. Click on the **Connect a domain** button:
-
-
-
-
The share modal
-
-
-
-Now, enter the custom domain you’d like to set, and then click the **Next: Configure DNS** button:
-
-
-
-
Connect a domain
-
-
-
-We’ll then provide the name and value to use in the next step when you create your CNAME DNS record. You can copy the name or value to your clipboard by clicking on the icon on the right-hand side of each field.
-
-
-
-
The CNAME value for your custom domain
-
-
-
-The value for the CNAME record will be in the format `[something]-hosting.gitbook.io`, where that `[something]` will be **unique to you**. Make sure to use the value displayed to you in the GitBook app, and _not_ the value in the screenshot above! 🙂
-
-Now, you’re ready to move onto the next step: [configuring DNS](../configure-dns.md).
diff --git a/publishing/custom-domain/location.md b/publishing/custom-domain/location.md
deleted file mode 100644
index c24990ad..00000000
--- a/publishing/custom-domain/location.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Deciding where to set the custom domain
-
-{% hint style="info" %}
-Please follow the steps to set a custom domain in this order:
-
-1. [Choosing a subdomain](choose.md)
-2. [**Deciding where to set the custom domain**](location.md) **(you are here)**
-3. [Initiating the custom domain setup](initiate/) (at the [organization](initiate/organization-level-custom-domain.md), [collection](initiate/collection-level-custom-domain.md), or [space](initiate/space-level-custom-domain.md) level)
-4. [Configuring DNS](configure-dns.md)
-5. [Confirming the custom domain setup](finalize.md)
- {% endhint %}
-
-There are three levels at which a custom domain can be set:
-
-1. [At the organization level](location.md#organization-level-custom-domains)
-2. [At the collection level](location.md#collection-level-custom-domains)
-3. [At the space level](location.md#space-level-custom-domains)
-
-This page provides more information about each of the options to help you decide where you want to set your custom domain.
-
-## Organization-level custom domains
-
-Because organizations contain collections and/or spaces, any custom domain set for the organization will have an effect on the domain for all collections and spaces within it, unless overridden by a custom domain set for a specific collection or space owned by the same organization.
-
-It’s important to note that **the custom domain you set will **_**not**_** be used as-is for any space within the organization**. Instead, each space will use the domain in this format: `[customdomain]/[spaceURL]`. The spaceURL part cannot be empty, and is set in the link and domain settings for each space.
-
-If you’ve decided that you want to set a custom domain at the organization level, you can [go to the next step](initiate/) for the details on how to set it. If you’re not sure, keep reading to review your other options.
-
-## Collection-level custom domains
-
-Because collections contain spaces, any custom domain set for the collection will have an effect on the domain for all spaces within it, unless overridden by a custom domain for a specific space within that collection.
-
-It’s important to note that **the custom domain you set will be used as-is for the **_**default**_** space in the collection**. Other spaces in the collection will have a URL in this format: `[yourcustomdomain]/v/[spaceURL]`. The spaceURL part cannot be empty, and is set in the link and domain settings for each space.
-
-If you’ve decided that you want to set a custom domain at the collection level, you can [go to the next step](initiate/) for the details on how to set it. If you’re not sure, keep reading to review your final option.
-
-## Space-level custom domains
-
-A custom domain set at the space level can override a custom domain set at the collection level (if the space is part of a collection) or at the organization level (if the space is owned by an organization).
-
-The custom domain you set will be used exactly as-is for the space.
-
-If you’ve decided that you want to set a custom domain at the space level, you can [go to the next step](initiate/) for the details on how to set it.
diff --git a/publishing/custom-domain/troubleshooting.md b/publishing/custom-domain/troubleshooting.md
deleted file mode 100644
index cff5f294..00000000
--- a/publishing/custom-domain/troubleshooting.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-description: >-
- Helping you to solve some of the most common issues when setting up a custom
- domain.
----
-
-# Troubleshooting
-
-On this page we’ll walk through some of the most common issues that folks run into when setting a custom domain, and explain how to solve them.
-
-
-
-SSL error: an error occurred when provisioning your SSL certificate.
-
-When a custom domain is set for your organization, collection, or space, we set up an SSL certificate on our end so that your documentation will load securely, over HTTPS. This happens automatically when you set your custom domain — you do not need to purchase or configure an SSL certificate yourself.
-
-Sometimes, though, there can be a problem at the stage where we set up the SSL certificate. Most often when this happens the issue is that the CNAME record for the custom domain has not fully taken effect, or _propagated_, yet.
-
-In these cases, we can recommend the following:
-
-1. Check that your CNAME record is set up correctly. Please review our page about [configuring DNS](configure-dns.md) to help you with this. If the CNAME record is incorrect, we will never be able to configure the SSL certificate and complete the setup of your custom domain. The value for the CNAME record will be displayed to you in the GitBook app, and will be in the format `[something]-hosting.gitbook.io` (where that `[something]` will be unique to you).
-2. Allow at least one hour between [configuring the CNAME record](configure-dns.md) and [finalizing the custom domain setup](finalize.md). This is because in _most_ cases, propagation will complete within one hour.
-3. Try using a third-party DNS lookup tool, such as [WhatsMyDNS](https://www.whatsmydns.net/), to find out what value servers located all around the world believe to be correct for your CNAME record. Type or paste your subdomain into the field, choose CNAME from the dropdown, and click on the search button. As propagation progresses, more and more servers will return the result that you expect. When the vast majority of these servers are reporting back the result that you expect, you can try moving onto the step of [finalizing the custom domain setup](finalize.md).
-4. If you are using Cloudflare, please confirm that you don’t have the record proxied [as explained here](configure-dns.md#are-you-using-cloudflare).
-
-If after trying those steps you are still having any trouble, please [contact the support team](../../help/support.md). In your message, please make sure to share:
-
-1. The subdomain that you would like to set as a custom domain; and
-2. The name of the organization, collection, or space for which you would like to set it.
-
-
-
-
-
-Domain already connected error: your subdomain is already configured for different content.
-
-The custom domain that you set for an organization, collection, or space needs to be unique. It is not possible to set the same custom domain in multiple places and, if you try to do so, you’ll run into this error.
-
-If this happens, you can click on the link within the error message to take a look at the content that the custom domain is already connected to. This may help you to decide what to do next. It’s also possible that you might not have access to the connected content — if that’s the case, [contact the support team](../../help/support.md) and they can help you with your next steps.
-
-The solution to this error will always be one of two things, however:
-
-1. Choose a different custom domain; or
-2. Disconnect the custom domain from the content it is already connected to, and then reconnect it to the new content.
-
-
-
-
-
-The custom domain is set correctly, but is redirecting to a different custom domain.
-
-This is _probably_ expected behaviour, but is something that you can change!
-
-The issue here is typically that custom domains have been set in more than one place. Keep in mind that when someone accesses the URL for an organization, they are taken straight to the organization’s default content. And likewise, when someone accesses the URL for a collection, they are taken straight to the collection’s default space. So, consider these examples:
-
-**Example 1**
-
-`docs.example.com` is set as the custom domain for an organization, and `team.example.com` is set as the custom domain for that organization’s default content. In this case, it would be expected that visiting `docs.example.com` would take you straight to `team.example.com`.
-
-One solution here could be to remove both docs.example.com and team.example.com and then re-add docs.example.com at the space-level.
-
-**Example 2**
-
-`products.example.com` is set as the custom domain for a collection, and `product1.example.com` is set as the custom domain for that collection’s default space. In this case, it would be expected that visiting `products.example.com` would take you straight to `product1.example.com`.
-
-So, whenever you set custom domains, make sure to consider this cascading effect when [deciding where to set each custom domain](location.md). If you see one custom domain redirecting to another, check what’s happening with custom domains at the organization-, collection-, and space-level. If, after checking, you still have questions, feel free to [contact the support team](../../help/support.md).
-
-
diff --git a/publishing/customization/README.md b/publishing/customization/README.md
deleted file mode 100644
index 022c7338..00000000
--- a/publishing/customization/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-description: >-
- Discover how you can align the look and feel of your GitBook spaces and
- collections with your own brand.
----
-
-# Customization
-
-You can customize the appearance of your public content, match the user interface to the language of your content, and manage public content integrations and features.
-
-Customization can be applied at a space or a collection level. Customizing a collection allows you to set top-level customizations that spaces within the collection can inherit.
-
-{% hint style="info" %}
-**Permissions**
-
-Admins and creators can customize spaces and collections.
-{% endhint %}
-
-### Learn more about:
-
-
diff --git a/publishing/customization/collection-customization.md b/publishing/customization/collection-customization.md
deleted file mode 100644
index 6d427c8f..00000000
--- a/publishing/customization/collection-customization.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-description: Customize your collection
----
-
-# Collection customization
-
-## Why publish and customize a collection?
-
-Collections are most commonly published and therefore customized when the user wants to share different language or product versions in one place. [Read more about sharing different language or product versions in one collection.](../share/collection-publishing.md)
-
-## How is customizing a collection different from customizing a space?
-
-Customizing a collection allows you to set top-level customizations that spaces within the collection can **inherit.** This is useful if you want to manage top-level customizations, letting you change customization options without having to change the settings for every space individually.
-
-
-
-
Collection customization settings
-
-
-
-Customizing your collection lets you control the branding, presentation and extra features of your collection’s published content.
-
-{% hint style="info" %}
-Most customization settings apply to your **published content**. This keeps your writing experience and in-app GitBook content consistent while allowing you to control the output to a degree.
-{% endhint %}
-
-### Customization options
-
-To learn more about each of the customization options read the guidance on [space customization](space-customization.md).
diff --git a/publishing/customization/space-customization.md b/publishing/customization/space-customization.md
deleted file mode 100644
index b8c993cb..00000000
--- a/publishing/customization/space-customization.md
+++ /dev/null
@@ -1,213 +0,0 @@
----
-description: Customize your space
----
-
-# Space customization
-
-
-
-
Space customization settings
-
-
-
-Customizing your space lets you control the branding, presentation and extra features of your space’s public content.
-
-{% hint style="info" %}
-Most customization settings apply to your **published content**. This keeps your writing experience and in-app GitBook content consistent while allowing you to control the output to a degree.
-{% endhint %}
-
-## General: control how your content looks
-
-
-
-Inherit customizations
-
-If the space you are customizing is within a collection, you’ll see this option:
-
-
-
-When this setting is enabled, the space will automatically inherit any changes made to the customization settings for the parent collection. This is useful if you want to control multiple spaces’ customizations in one place, and removes the need to make the same change multiple times across spaces.
-
-
-
-
-
-Basic (icon, title, logo)
-
-**Icon**\
-You can set an emoji, or upload an icon of your own. Please note that this setting will only affect the icon that displays _in the published documentation_ and it’ll be used as the favicon for the page. (If you want to edit the icon used within the GitBook app, close the customize section and click on the icon at the top of the space.)
-
-**Title**\
-You can set any title you choose for your space. Again, please note that this setting will only affect the title that displays _in the published documentation_. (If you want to edit the title used within the GitBook app, close the customize section and click on the title at the top of the space.)
-
-**Logo**\
-You can replace _both_ the space’s title and icon with a custom logo so that your documentation better reflects your own branding — and, you can upload two versions: one for light mode, and one for dark mode. _Note: this setting is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan._
-
-If you’re wondering about the difference between the icon and logo options, here’s the answer! The icon allows you to upload a small, 132px square image, which will be displayed _alongside_ your space title, whereas the custom logo allows you to upload a larger image (we recommend at least 600px wide), which will completely replace the icon and title settings.
-
-
-
-
-
-Themes (with light & dark modes)
-
-Themes enable you to customize the color scheme of your published content. Whichever theme you choose, you’ll have access to choose the primary color for light mode and for dark mode. While you can use any colors you’d like, it’s important to keep accessibility in mind and choose something that will have good contrast so that your content is easy to read.
-
-**Default theme**\
-All spaces have access to this theme, where the header background color will be aligned with the background color for the rest of the space.
-
-**Bold theme**\
-The bold theme uses the primary color as the header background color. It is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan.
-
-**Contrast theme**\
-The contrast theme has a dark header background color in light mode, and a light header background color in dark mode. It is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan.
-
-**Custom theme**\
-The custom theme option will enable you to set your own color preferences for the background color and link color in the header, in addition to choosing the primary color for light mode and for dark mode. It is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan.\
-
-
-
-
-
-Modes
-
-**Show mode toggle**\
-If you would like visitors to your published content to be able to toggle between light and dark mode, enable this setting! You can see it in action in our own documentation here. It’s located near the top-right corner next to the search bar for larger screens, and within the menu on mobile devices.
-
-**Default mode**\
-Choose whether visitors to your published content will see it in light mode or dark mode initially. If show mode toggle is enabled, they’ll be able to switch to the other option if they prefer. If show mode toggle is disabled, they’ll only be able to see your content in the mode you choose here.
-
-_Note: if, instead, you’re looking to change the theme within the GitBook app, you can do that from your settings menu, which can be found at the bottom of the_ [_sidebar_](../../product-tour/navigation.md#sidebar)_._
-
-
-
-
-
-Styling
-
-**Font family**\
-You can choose a font family for your published content from a list of popular options. This setting is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan.
-
-GitBook doesn’t support the uploading or linking of custom fonts. If you think we’re missing a typeface that works wonderfully for headers, body copy, and captions, [let us know](../../help/support.md)!
-
-**Corner style**\
-Choose either a rounded corner or straight corner style, to help align your published GitBook content with your own brand’s styling preferences.
-
-
-
-## Layout: manage navigation options for your content
-
-
-
-Header
-
-**Navigation**\
-Enable or disable header links for your space! You could use header links to link to important parts of your documentation, or perhaps to link back to your main website.
-
-When enabled, all you’ll need to do is add a title and a URL for each link. We support two levels of header navigation, meaning that you can have sub-links that appear in a dropdown menu.
-
-
-
-
-
-Page
-
-**Pagination**\
-Keep this setting on to have previous and next buttons appear at the bottom of each page in your space, or toggle it off if you prefer that your pages don’t include those buttons.
-
-
-
-
-
-Footer
-
-Enable or disable a footer section for your space! The footer is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan.
-
-**Logo**\
-You might like to include your logo or another image in the footer. If you choose to upload one, we recommend a width of at least 600px.
-
-**Copyright text**\
-You can include some brief copyright text, if you’d like.
-
-**Navigation**\
-You can include links in your footer, in multiple sections. Just like with the header, you just need to add a title and URL for each link. Make sure to also include a section title for each section you create.
-
-
-
-## Sharing: customize social media preview
-
-
-
-Social preview
-
-You can upload a custom social preview image for your space. This will set the space’s `og:image` to be your uploaded image, and it’ll show when the space’s link is shared to any platform or product that supports OpenGraph images.
-
-
-
-## Configure: manage the interface
-
-
-
-Localize user interface
-
-You can select from a list of languages to localize the user interface of your published content. This will apply translations to the **non-custom** areas of the interface.
-
-This setting will _not_ auto-translate your actual content, but can help with matching the user interface to the language that you are writing in.
-
-Is there a language we don’t yet offer that you would like to see included in this list? [Let us know](../../help/support.md)!
-
-
-
-
-
-Enable Lens semantic search
-
-Enabling Lens allows visitors to your published documentation to ask questions and receive a semantic answer based on your content.
-
-You can [find out more about Lens](../../product-tour/searching-your-content/lens.md).
-
-
-
-
-
-PDF Export
-
-You can choose whether or not you’d like visitors to your published content to be able to download the content as a PDF file.
-
-You can [find out more about the PDF export feature](../share/pdf-export.md).
-
-PDF Export is only available to spaces owned by an organization subscribed to a Pro or Enterprise plan.
-
-
-
-
-
-Page Rating
-
-Choose whether or not visitors to your published content can leave a rating on each page to let you know how they feel about it. They’ll be able to choose a sad, neutral, or happy face.
-
-You can review the results of this survey if you click on [insights](../insights.md) in the [space sub-navigation](https://docs.gitbook.com/getting-started/overview#space-sub-navigation).
-
-
-
-
-
-Privacy Policy
-
-You can link to your own privacy policy to help visitors understand how your GitBook content uses cookies, and how you protect their privacy. If you choose not to set one, [GitBook’s own privacy policy](https://policies.gitbook.com/privacy-and-security/statement/cookies) will be used.
-
-
-
-## Integrations
-
-You can choose to enable[ Intercom](broken-reference) or [Google Analytics](broken-reference) integrations for your published content.
-
-Looking for more? [Read about our integrations](space-customization.md#integrations), which include [Segment](broken-reference), [Plausible](broken-reference) and [Fathom.](broken-reference)
-
-## What _can’t_ be customized?
-
-The options above provide lots of ways for you to customize your space, but there are a few things that you won’t be able to customize, regardless of [your chosen plan](../../account-management/plans/).
-
-1. It’s not possible to customize the layout of the elements on the page. (However, it _is_ possible to [hide certain elements](../share/page-layouts.md) on a page-by-page basis.)
-2. There’s no way to insert custom code (such as CSS, HTML, JS, etc.) directly into one or more documentation pages. (If you’re looking to integrate a third party service, take a look at [the docs for our integrations platform](https://developer.gitbook.com/)!)
-3. It’s not possible to remove the small "Powered by GitBook" link that appears in published documentation.
diff --git a/publishing/insights.md b/publishing/insights.md
deleted file mode 100644
index 0f24c94f..00000000
--- a/publishing/insights.md
+++ /dev/null
@@ -1,75 +0,0 @@
----
-description: >-
- Learn about the native insights GitBook provides for your public
- documentation.
----
-
-# Gather insights on your content
-
-You can measure and improve your documentation by checking how your pages are performing and which keywords are used when searching through your documentation.
-
-{% hint style="info" %}
-**Permissions**
-
-Administrators and creators can view the insights panel.
-{% endhint %}
-
-## The insights panel
-
-When inside a space, click on **insights** in the [space sub-navigation](https://docs.gitbook.com/getting-started/overview#space-sub-navigation) to open the insights panel. You’ll see two tabs: pages and searches.
-
-
-
-
Preview of the sub-navigation panel with insights visible. This view is available to admins and creators
-
-
-
-#### Pages tab
-
-
-
-Traffic
-
-This shows a summary of visits to your space across all pages. You can view daily, weekly, or monthly traffic — monthly is the default. A bar chart plots that traffic over time.
-
-
-
-
-
-Pages
-
-For each page in the space, you can see a count of all views. This is the **total number of views since the page was published**. If [page rating](https://docs.gitbook.com/tour/customization/space-customization#page-rating) is enabled, you can also see how many people have left feedback on each page and the average feedback rating. Hover over the average rating to see further details.
-
-Click **download CSV** if you’d like to use or analyse this data further outside of GitBook, and a `.csv` file will be downloaded to your device.
-
-
-
-#### Search tab
-
-
-
-Searches
-
-Switch to the search tab to take a look at which terms visitors are searching for within the space. You can view these search terms for the past week, month, or year — and again, the month is the default setting.
-
-The information here can be helpful for informing your content architecture, making certain parts of your documentation easier to find without search, or adding additional content to existing pages based on what your visitors are searching for.
-
-Click **download CSV** if you’d like to use or analyse this data further outside of GitBook, and a `.csv` file will be downloaded to your device.
-
-
-
-{% hint style="info" %}
-**Why can’t I see any data for my space?** We display data only for **published** spaces. That means that if your space is shared internally with the members of your organization, you will not see any insights into this space.
-{% endhint %}
-
-## FAQ: Feedback, analytics and insights
-
-### Can I integrate GitBook with other analytics tools?
-
-GitBook default insights offer a quick overview of page views. To take a deeper look into your readers’ behaviour, you should take a look at our [Google Analytics](customization/space-customization.md#google-analytics), [Plausible](broken-reference) or [Fathom](broken-reference) integrations.
-
-### Can I get more detailed information besides page ratings?
-
-Page ratings can be set in the customization settings, allowing users to provide a basic rating on the content. The summary of those votes can be accessed through insights in the [page tab](insights.md#pages).
-
-At the moment we don’t offer any options to integrate or gather feedback from users. If you would like to see us implement more options please submit them as a feature request in [our community.](https://github.com/GitbookIO/community/discussions)
diff --git a/publishing/internationalization.md b/publishing/internationalization.md
deleted file mode 100644
index 194a922f..00000000
--- a/publishing/internationalization.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-description: Helping your GitBook documentation to reach people in multiple languages.
----
-
-# Match the UI to the language of your content
-
-GitBook supports the internationalization of a space or a collection, enabling public documentation user interface elements to be translated.
-
-{% hint style="info" %}
-**Permissions**
-
-Administrators and creators can change the language of the user interface for public documentation.
-{% endhint %}
-
-## Choosing a language for your content
-
-Currently, the supported languages are English, French, Spanish, Chinese (simplified), and Japanese.
-
-By default, your content will have the **English** language selected. To change this, click **customize** in the [space sub-navigation](https://docs.gitbook.com/getting-started/overview#space-sub-navigation), go to the **configure** tab, and use the dropdown menu in the **localize user interface** setting.
-
-
-
-
Choose your preferred language for the user interface elements of your published documentation
-
-
-
-### Inheriting language settings
-
-If a space is inside a collection, you can set the localization language for that space to inherit. This will keep the space’s localization language in sync with the setting at the collection level. Choosing a different language for one space inside a collection would override the collection-level setting.
-
-## Publishing your content in different languages
-
-If you would like to [share a different language (or product) version](share/collection-publishing.md), you will have to publish a collection as a variant. This enables you to create a space per language and publish the collection as a unified UI, allowing readers to switch seamlessly between different language spaces.
diff --git a/publishing/seo.md b/publishing/seo.md
deleted file mode 100644
index f312bc5f..00000000
--- a/publishing/seo.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-description: Optimize your GitBook documentation to be discoverable via search engines.
----
-
-# SEO
-
-Thanks to the following features, your GitBook projects are SEO-friendly with little or no configuration on your end:
-
-
-
-Responsive design
-
-All content is suitable for mobile devices, tablets, laptops and desktops! The design for your published documentation will adapt based on the size of the device it is being viewed on.
-
-
-
-
-
-SEO-friendly content
-
-- URLs are set based on each page’s title by default, but can be customized as you wish.
-- We avoid duplicate content through smart, canonical URLs.
-- The HTML title and Open Graph title are based on the page and space title.
-- The meta description and Open Graph description are based on the page description.
-- Alt text can be added to images, which is also very important for accessibility.
-- HTML sent to crawlers is pre-rendered (i.e. server-side), meaning that crawlers do not need JavaScript to index your content.
-
-Note that we _don’t_ generate keyword meta tags, because modern search engines do not use them to rank pages. This was [officially confirmed by Google](https://developers.google.com/search/blog/2009/09/google-does-not-use-keywords-meta-tag) in 2009.
-
-
-
-
-
-Sitemap
-
-Provided that your space is published with a setting _other_ than [unlisted](share/space-publishing.md#unlisted-space), we automatically generate a sitemap.xml file based on your [table of contents](https://docs.gitbook.com/getting-started/overview#table-of-contents). You can locate this by going to the first page of your documentation and then appending `/sitemap.xml` to the URL. For example, the first page of our documentation is located at [docs.gitbook.com](https://docs.gitbook.com/), and so our sitemap.xml file is located at [docs.gitbook.com/sitemap.xml](https://docs.gitbook.com/sitemap.xml).
-
-
-
-
-
-Custom domain
-
-If you prefer, you can [set a custom domain](custom-domain/) for your documentation. (e.g. `docs.example.com` instead of `yourorganization.gitbook.io`)
-
-
-
-
-
-Caching & CDN
-
-All published content is cached and served via our global CDN (content delivery network). This helps to improve performance, which is an important factor within SEO.
-
-
-
-Even with these great features, it could still take some time before your documentation is indexed by Google (and other search engines). Both we and you have no _direct_ control over this, but there are two things that you could do to help improve the chance of getting your content indexed more quickly:
-
-1. Make sure that there are links to your GitBook space from other websites that have already been indexed by Google. As Google will return to re-index these sites from time to time, this increases the chance that they’ll find your space as a result of re-indexing one of these other sites.
-2. Try [submitting your site to Google](https://developers.google.com/search/docs/advanced/crawling/ask-google-to-recrawl), which essentially asks them to index it. For GitBook spaces, this will only be possible if you are using a [custom domain](custom-domain/) for your space _and_ if you create a TXT DNS record to confirm ownership of the domain.
-
-### Redirects
-
-Moving your content to GitBook or changing its structure? Broken links can impact your SEO. [Read how to set up redirects in GitBook (via Git sync)](../integrations/git-sync/content-configuration.md#redirects).
diff --git a/publishing/share/README.md b/publishing/share/README.md
deleted file mode 100644
index 81e1e32d..00000000
--- a/publishing/share/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-description: >-
- Discover the range of publishing options offered, including public or
- read-only links.
----
-
-# Share your content
-
-GitBook has different sharing options for you to choose from, depending on who you want to be able to access your content.
-
-You can make your content completely [public](space-publishing.md#public-space) to anyone on the internet. Or, you can share more securely using [share links](share-links.md) or [visitor authentication](space-publishing.md#visitor-authentication).
-
-You can also use collection publishing to [publish different versions of your documentation](collection-publishing.md#how-to-publish-a-collection-of-variants). For example, you might want to publish your documentation in different languages, or you might want to publish documentation for each version of your product.
-
-{% hint style="info" %}
-**Permissions**
-
-Only creators and administrators can publish content.
-{% endhint %}
-
-### Learn more about:
-
-
Sharing options
Learn how to share a single space about discover publishing options for spaces.
diff --git a/publishing/share/collection-publishing.md b/publishing/share/collection-publishing.md
deleted file mode 100644
index dad496a4..00000000
--- a/publishing/share/collection-publishing.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-description: Learn about publishing a collection as a container for variants.
----
-
-# Share different language or product versions in one place
-
-If you want to publish multiple versions of your documentation in one place, such as in different languages or different versions of your product, you can use **collection publishing**.
-
-{% hint style="info" %}
-**Permissions**
-
-Only creators and administrators can publish content.
-{% endhint %}
-
-## Why publish spaces in a collection?
-
-When you set the [space visibility](space-publishing.md) of a space to **in collection** and publish the collection, you can wrap a number of spaces in a single published interface. We call this **publishing variants**.
-
-When you publish a collection of variants, any child space that is published inside the collection will be quickly accessible through a dropdown in the sidebar of the published content, allowing readers to switch between variants at any time.
-
-Variants are useful if you need to offer a grouped experience for spaces, such as documenting multiple versions of an API (v1, v2, v3, etc.) or documenting your content in multiple languages.
-
-
-
-
Switching between variants in published documentation
-
-
-
-Here are some examples of how GitBook users have published variants in collections:
-
-- [Pancake Swap](https://docs.pancakeswap.finance/) use variants to publish its documentation in different languages
-- [Forest Admin](https://docs.forestadmin.com/documentation/) use variants to publish different versions of their documentation in one place
-
-## Spaces inside a published collection
-
-When you publish a collection, you still need to decide which spaces nested within the collection should be published as part of that collection. This might be a little confusing at first, but it lets you maintain private spaces inside a published collection.
-
-As an example, maybe you’ve got a collection full of useful spaces, but you’re working on a completely new space to live alongside them. Rather than creating and editing that space somewhere else, you can keep it where it’s supposed to live, and only publish it as part of the collection when it’s ready.
-
-## How to publish collection with variants
-
-We will use the example of publishing product documentation in multiple languages. The same logic applies to publishing other types of variants such as multiple versions of an API (v1, v2, v3, etc.).
-
-You should create a collection to hold your spaces/variants. You can see in the screenshot below that we have a collection called My Product Docs. Inside the collection are 2 spaces: English and Spanish. As the names suggest, the English space contains our product documentation written in English, and the Spanish space contains the Spanish translation.
-
-
-
-
A collection with two variants
-
-
-
-
-
-Step 1: Publish the collection
-
-First we will publish the collection. Note that this **does not publish the spaces inside the collection**. You need to publish each space individually.
-
-Collection publishing works almost exactly the same as [space publishing](space-publishing.md#publish-to-the-web). Navigate to the the **share** button near the top-right corner, which will open the share modal.
-
-Inside the share modal, you’ll see some or all of the following tabs on the left-hand side to choose from. (The tabs available to you will depend on your permissions.)
-
-
-
-
-
-Step 2: Publish spaces in collection
-
-For each space that you want to publish in the collection, click on the **share** button near the top-right corner to open the share modal.
-
-This action will create variants that will be displayed inside your collection.
-
-Ensure you’re on the publish to the web tab, and then toggle the publish in collection setting to the **on** position.
-
-
-
-
Publish variants of spaces in one collection
-
-### How to set the main space in a collection
-
-The default space in a collection is the space that readers will land on when they visit your published collection.
-
-To change the default space in a collection, navigate to the collection customization page by clicking the triple dot menu button in the top-right corner of the collection in the editor. Under General > Collection, choose the default space from the dropdown.
-
-
Change the default space in a published collection
-
-{% hint style="info" %}
-Did you know you can extend GitBook through integrations? GitBook’s Integration Platform allows you to enhance the way you work—Including helping you with translations of the things you write. \
-\
-Head to our guide on [translating GitBook pages](https://developer.gitbook.com/getting-started/guides/use-github-actions-to-translate-gitbook-pages) to learn more.
-{% endhint %}
diff --git a/publishing/share/page-layouts.md b/publishing/share/page-layouts.md
deleted file mode 100644
index 131c4129..00000000
--- a/publishing/share/page-layouts.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Page options & covers
-
-You can find the links to set page options and page covers by hovering over the page title. You’ll see the links appear just above the page title.
-
-## Page options
-
-Page options allow you to select how each page is displayed to those who visit your _published_ content. There are three layout presets to choose from, or you can create a custom layout.
-
-Each layout preset will toggle on or off each of the following parts of the page:
-
-- Page title
-- Page description
-- Table of contents
-- Page outline
-- Next/previous links
-
-Take a look at how each preset will set each of these parts of the page:
-
-
Part of the page
Docs layout
Editorial layout
Landing page layout
Page title
true
true
true
Page description
true
true
true
Table of contents
true
false
false
Page outline
true
true
false
Next/previous links
true
true
true
-
-If you want to use a custom layout, you can choose the custom option and then start toggling the settings on and off — or, you can simply toggle a setting while another layout is chosen and we’ll automatically switch to custom for you.
-
-{% hint style="info" %}
-Remember that the settings you choose here will affect the **published content**.
-{% endhint %}
-
-## Page covers
-
-You can also set a page cover for each page of your documentation. When you click the page cover link, a cover will be added immediately. From there, you can:
-
-- **Change the cover image**
-
- Click the button that appears on the cover when you hover over it, and choose or upload an image. Based on how we currently display the page cover, 1990x480 pixels is the ideal size.
-
-- **Reposition the cover image**
-
- Click the three-dot icon that appears on the cover when you hover over it, click reposition, then drag the image as you wish and click save.
-
-- **Remove the cover image**\
- Click the three-dot icon that appears on the cover when you hover over it and then click remove.
diff --git a/publishing/share/pdf-export.md b/publishing/share/pdf-export.md
deleted file mode 100644
index 0e143065..00000000
--- a/publishing/share/pdf-export.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-description: Learn how to export a PDF copy of your content on GitBook.
----
-
-# PDF export
-
-The PDF export is available with a **Pro** or **Enterprise** plan. It allows:
-
-1. Visitors to your published content to download the space as a PDF file.
-2. You and other logged-in users to export a single page, a page with its subpages, or an entire space as a PDF file.
-
-{% hint style="info" %}
-**Permissions**
-
-Admins and creators can enable and disable PDF export for a space.
-{% endhint %}
-
-## Allow readers to export a PDF version of your content
-
-To enable or disable PDF export for your readers, head to the customization settings for a space or collection. On the configure tab, you can enable or disable the PDF export setting. This setting determines whether or not **readers of your published content can download it in PDF format**.
-
-
-
-
Enable or disable PDF export for your published content
-
-
-
-## Export your own content as PDF
-
-Regardless of the configured customization setting shown above, members of an organization (on the Pro or Enterprise plan) who are logged in to the app can export a page, or an entire space as a PDF file.
-
-### How to export an individual page
-
-1. You can access the export menu through [page actions](https://docs.gitbook.com/getting-started/overview#page-actions) which are displayed on the right-hand side of the editor. Alternatively, navigate to the **share** button in the top right-hand corner and click on 'Export as PDF' in the share modal.
-2. Go to the page that you would like to export, and click **export as PDF** in page actions.
-3. Select **only this page**.
-4. Click the **export** button.
-5. Wait for the PDF file to be created, then click the **download** button.
-
-
-
-
Export "Only this page" as a PDF
-
-
-
-### How to export an entire space
-
-1. Navigate to the [page actions](https://docs.gitbook.com/getting-started/overview#page-actions) menu on the right-hand side of the editor. Alternatively, navigate to the **share** button in the top right-hand corner and click on 'Export as PDF' in the share modal.
-2. Go to any page within the space you'd like to export and click **export as PDF** in page actions.
-3. Select the **entire space**.
-4. Click the **export** button.
-5. Wait for the PDF file to be created, then click the **download** button.
-
-
-
-
Export "Entire Space" as a PDF
-
-
diff --git a/publishing/share/share-links.md b/publishing/share/share-links.md
deleted file mode 100644
index 25fae009..00000000
--- a/publishing/share/share-links.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-description: >-
- Share links give you greater control over who can view your GitBook
- documentation.
----
-
-# Share privately with a secure link
-
-{% hint style="info" %}
-This feature is available on our **Pro** and **Enterprise** plans.
-{% endhint %}
-
-Share your private content with customers and partners without inviting them to your organization by using a secret shareable link or links!
-
-## Publish via share link
-
-
-
-
A GitBook space published via share link
-
-
-
-To publish via share link(s), open the space or collection you want to share in GitBook. Open the share menu and select **share to an audience**.
-
-Next, click on **publish with share links** to access your share links. In this area will be able to review and name your share links, customize the UR and copy the links.
-
-
-
-
Link and domain settings for a GitBook space published via share link
-
-
-
-Once the link is active, a private token is generated within your URL, which is unique to your space. Sharing this link will give non-GitBook users access to your private content in read mode only.
-
-{% hint style="info" %}
-Share links can be [revoked](share-links.md#revoke-a-link) and regenerated at any time.
-{% endhint %}
-
-## Permissions
-
-The content will be accessible to **anyone following the link**. Your team members will always be able to access your content from their dashboard.
-
-{% hint style="info" %}
-Make sure you share the link only with people you want to share your private content. Don’t forget that you can [revoke](share-links.md#revoke-a-link) a link at any time.
-{% endhint %}
-
-## Revoke a link
-
-The shareable link can be disabled or regenerated by revoking a link. You can see and revoke any previously generated link by opening the visibility menu and clicking through to link and domain settings.
-
-{% hint style="warning" %}
-**Heads up!** Anyone using a revoked link will no longer have access to your content.
-{% endhint %}
-
-## Other secure sharing options
-
-### Privacy of my content is not critical
-
-If you don’t have strong privacy and security requirements, a better solution may be to publish the space as [unlisted](https://docs.gitbook.com/getting-started/publishing/space-publishing#unlisted-space). Unlisted spaces are not indexed by search engines, and therefore will not be easily discoverable.
-
-### I need a more secure alternative
-
-#### Internal users
-
-The most secure way to share your content with a private audience is to have them create a GitBook account and join your organization.
-
-This process can be [automated using SSO/SAML](../publishing/broken-reference/), which can be used to create custom authentication for your documentation. This will require setup on your end to integrate with your chosen identity provider.
-
-**External users**
-
-If you would like to share your **public** content with a large number of authenticated visitors, you might like to use our [visitor authentication](../visitor-authentication.md) feature. This would allow you to design your own flow allowing you to authenticate users via a token. This solution requires engineering resources from your side - you can preview an example repository for [Node.JS on GitHub.](https://github.com/GitbookIO/example-visitor-authentication)
diff --git a/publishing/share/space-publishing.md b/publishing/share/space-publishing.md
deleted file mode 100644
index 0fb24671..00000000
--- a/publishing/share/space-publishing.md
+++ /dev/null
@@ -1,94 +0,0 @@
----
-description: Learn about the different options for sharing your GitBook space.
----
-
-# Sharing options
-
-## Sharing a space
-
-To share a space, start by clicking the **share** button, which you’ll find near the top-right corner of each space. This will open the share modal.
-
-
-
-
To share a space, start by clicking the share button. This will open the share modal.
-
-
-
-Inside the share modal, you’ll see tabs on the left-hand side to choose from.
-
-{% hint style="info" %}
-**The range of tabs available to you will depend on your permissions in the space.**
-{% endhint %}
-
-## What sharing options are available?
-
-### Invite members
-
-
-
-
-
-
-
-By default, users within your organization will inherit the permissions assigned to them within the organization settings area.
-
-If you want your content to remain private, and shared only with a specific person or group, inviting that person or people to be a member of your organization could be a great choice. They will be able to access the content when they are logged into their GitBook account.
-
-
-
-Invite members (visible only to organization administrators)
-
-Inviting a member will make them a member of the organization that owns the space, which will increase your overall subscription charge.
-
-The cost for this will depend on the [plan](../../account-management/plans/) that the organization is subscribed to.
-
-It is also possible to [invite members to the organization ](../../account-management/member-management/invite-members-to-your-organization.md)from within the organization settings area.
-
-
-
-### Publish to the web
-
-
-
-
Preview of a share modal opened on the public sharing option
-
-
-
-If your content is suited for a much wider audience, you can publish it on the web. \
-Spaces that are published on the web can be [indexed by search engines](../seo.md) and will be available to **anyone** on the Internet.
-
-You’ll still retain control over who can _edit_ your content, and only your primary content branch will be published, so any [change requests](../../collaboration/collaboration/change-requests.md) will remain private until merged.
-
-### Share to an audience
-
-
Preview of the share modal opened on the share to an audience option
-
-In some cases, you might want to publish your content, but only permit certain people to access it. We offer a number of options for this:
-
-#### **Publish in collection**
-
-{% hint style="info" %}
-This option will only be visible if your collection has been published first.
-{% endhint %}
-
-If the space is nested inside of a published collection, you’ll see this option. A space nested inside of a collection does not _have_ to be published as part of the collection so you can do things like work on a new version and only publish it when it’s ready. Toggle this option to publish the space as part of the collection. You can [find out more about collection publishing](collection-publishing.md).
-
-#### **Publish with** **visitor authentication**
-
-With visitor authentication, GitBook lets _your_ server-side code handle who has access to the content. [Find out more about visitor authentication](../visitor-authentication.md).
-
-#### **Publish with** **share links**
-
-Share links include a private token, making it extremely difficult for anyone outside of those you share the link with to find the content. This can be a great way to share private content with those who are not members of your organization. [Find out more about share links](share-links.md).
-
-#### **Publish as unlisted**
-
-Unlisted spaces are publicly available, but they _won’t_ be indexed by search engines such as Google. They will still be accessible to anyone on the Internet who knows (or can guess) the link to your documentation. Unlisted spaces can be particularly helpful if you want to publish a beta of your docs, or do large-scale user testing, without impacting your SEO with potentially duplicate content, etc.
-
-### Export as PDF
-
-This option allows you to generate a PDF copy of your content and share this with others in any way you choose. You can export one or more single pages or the entire space in one PDF file. [Find out more about PDF export.](pdf-export.md)
-
-### Who can access?
-
-This tab confirms the current visibility of the space, along with who has access to it within the GitBook app. No settings can be changed here; all changes are made from within the other tabs.
diff --git a/publishing/visitor-authentication.md b/publishing/visitor-authentication.md
deleted file mode 100644
index 3f68a69c..00000000
--- a/publishing/visitor-authentication.md
+++ /dev/null
@@ -1,146 +0,0 @@
----
-description: Use JWT token to authorize anonymous access to private content.
----
-
-# Visitor authentication
-
-{% hint style="info" %}
-This feature is currently accessible to all **Pro and Enterprise** customers. If you are interested in the [Enterprise plan](../account-management/plans/#enterprise-plan), please contact [sales@gitbook.com](mailto:sales@gitbook.com) for a quote.
-{% endhint %}
-
-GitBook provides different solutions to handle access management:
-
-* Private content accessible to members only
-* SAML SSO
-* public content accessible to anyone
-
-With visitor authentication, GitBook lets your server-side code handle who has access to the content.
-
-## How does it work?
-
-
-
-## Setup Guide
-
-{% hint style="info" %}
-A complete example repository for Node.JS is available on GitHub: [https://github.com/GitbookIO/example-visitor-authentication](https://github.com/GitbookIO/example-visitor-authentication)
-{% endhint %}
-
-### Step 1: enable visitor authentication
-
-In your space or collection, open the visibility menu and select **visitor authentication**. (If you're not on an Enterprise plan, you'll be prompted to upgrade.)
-
-
-
-Once enabled, you'll have access to a private signing key for this space. Each space has a unique signing key. You should keep this key secret - make sure not to commit it into your source control repository. We recommend referencing it through a production secrets system in your deployed backend.
-
-
-
-### Step 2: sign a JWT token and grant access to a visitor
-
-Here's an example of creating a JWT token by signing the access data with the private key using the library [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) for Node JS.
-
-```javascript
-const jwt = require('jsonwebtoken');
-
-const gitbookSignKey = ''
-
-const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
-const redirectURL = `https://mycompany.gitbook.io/myspace/?jwt_token=${token}`;
-```
-
-Once you've created the key, you need to include it as the value of a query parameter named `jwt_token` the URL of the GitBook content you wish the user to have access to (see `redirectURL`)
-
-Here's a very simple Express application for signing keys and redirecting users:
-
-```javascript
-const express = require('express');
-const jwt = require('jsonwebtoken');
-const app = express();
-const port = 3000;
-
-const gitbookSignKey = ''
-
-app.get('/', (req, res) => {
- // --> Validate user access here <--
-
- const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
- const redirectURL = `https://mycompany.gitbook.io/myspace/?jwt_token=${token}`;
-
- res.redirect(redirectURL);
-});
-
-app.listen(port, () => {
- console.log(`Example app listening at http://localhost:${port}`)
-});
-```
-
-### Step 3: configure a fallback URL
-
-Finally, within **link and domain settings** in the visibility menu, you can configure a fallback URL.
-
-When someone directly accesses your space without the necessary token, GitBook uses the fallback URL to redirect the visitor to a custom URL so that you can authenticate them.
-
-
-
-When redirecting to the fallback URL, GitBook is passing a `location` query parameter, it can be used to redirect to the original location of the user:
-
-```javascript
-// Route handler for the fallback url
-app.get('/', (req, res) => {
- // --> Validate user access here <--
-
- const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
- const redirectURL = `https://mycompany.gitbook.io/myspace/${req.query.location || ''}?jwt_token=${token}`;
-
- res.redirect(redirectURL);
-```
-
-## Multi-tenant Visitor Authentication
-
-If you're using GitBook as a platform for providing content to your customers, you are probably looking for multi-tenant visitor authentication. Essentially, your authentication server needs to be responsible for handling authentication across multiple different spaces. This is possible in GitBook with a few small tweaks.
-
-### Adding all tenants to your authentication server
-
-Your authentication server will need to know the JWT signing keys and the URLs of all the GitBook spaces you expect it to handle. If you have two spaces in your organization for CustomerA and CustomerB, you can imagine your authentication server storing:
-
-```javascript
-const CUSTOMER_A = {
- jwtSigningKey: 'aaa-aaa-aaa-aaa',
- url: 'https://mycompany.gitbook.io/customer-a'
-};
-
-const CUSTOMER_B = {
- jwtSigningKey: 'bbb-bbb-bbb-bbb',
- url: 'https://mycompany.gitbook.io/customer-b'
-};
-```
-
-### Giving your authentication server additional context
-
-When GitBook cannot authenticate a user's request, it redirects to the fallback URL. This fallback URL is your authentication server, and GitBook is asking it to authenticate the user and then bring them back to the content.
-
-In order to handle multiple tenants, your authentication server needs to be told an additional piece of information: which space is the user trying to access? We do this by adding extra information to the fallback URL.
-
-
A fallback URL with additional information
-
-Your authentication server can now check the value of this field, and handle it accordingly:
-
-```javascript
-app.get('/', (req, res) => {
- const customerInfo = req.query.space === 'customer-a' ? CUSTOMER_A : CUSTOMER_B;
-
- const token = jwt.sign({}, customerInfo.jwtSigningKey, { expiresIn: '1h' });
- const redirectURL = `${customerInfo.url}/${req.query.location || ''}?jwt_token=${token}`;
-
- res.redirect(redirectURL);
-});
-```
-
-## Custom Domains
-
-Visitor Authentication works well with custom domains. If a space published with has a custom domain like `customera.mycompany.com`, then visitors to `customera.mycompany.com` will be taken through the Visitor Auth flow and eventually redirected back to the space.
-
-## Resources
-
-Head to our [developer documentation](https://developer.gitbook.com/getting-started/guides) to view the various guides we have on setting up Visitor Authentication with different providers.
diff --git a/resources/gitbook-ui.md b/resources/gitbook-ui.md
new file mode 100644
index 00000000..d241998a
--- /dev/null
+++ b/resources/gitbook-ui.md
@@ -0,0 +1,198 @@
+---
+description: Learn about the different components and UI in GitBook’s editor
+icon: sidebar
+---
+
+# GitBook UI
+
+Learn about the different components and UI in GitBook’s editor
+
+GitBook is split into different sections to make it easier to organize and manage the content you create.
+
+### Sidebar
+
+
The GitBook sidebar holds all of your documentation, as well as notifications, the search bar, snippets and more.
+
+The sidebar allows you to see and overview of your GitBook organization at a glance. The sidebar contains:
+
+* **Organization switcher**\
+ If you’re a part of multiple organizations, you can see and switch between them here. You can also create a new organization from this menu.
+* **Notifications**\
+ When you’re tagged in a comment or conversation, or when there is important activity in a space you’re working in, you’ll get a [notification](../collaboration/notifications.md) to show you what’s new.
+* **Ask or search**\
+ Powered by [GitBook AI](../creating-content/searching-your-content/gitbook-ai.md), you can ask questions in natural language, or search through the different spaces and content in your organization.
+* **Home**\
+ The Home page allows you to see everything your team is working on at a glance. View open change requests, discussions and comments, recent page edits and more.
+* **Docs sites home**\
+ Click this to visit the overview page for all the docs sites you have created in your organization.
+* **Integrations**\
+ GitBook [integrations](../content-editor/editor/broken-reference/) supercharge your content, allowing you to embed more into your pages, or add information to your knowledge base from other apps.
+* **Docs sites**\
+ Toggle this section to view all the [docs sites](../publishing-documentation/publish-a-docs-site/) in your organization right in the sidebar and jump to one with a click.
+* **Spaces**\
+ The spaces section is where you’ll find the [collections](../creating-content/content-structure/collection.md) and [spaces](../creating-content/content-structure/space.md) you create when adding more content. Head to our [content structure](../creating-content/content-structure/) section to find out more.
+* **Settings**\
+ You’ll find [personal settings](../account-management/account-settings.md) and [organization settings](../account-management/organization-settings.md) at the bottom of the sidebar. Here, you can also toggle light/dark mode, or get help from our support team if needed.
+* **Trash**\
+ Deleted spaces appear in the trash. You can restore them for up to seven days — after that, they’re permanently deleted.
+
+### Table of contents
+
+
The table of contents lists all the pages and links in your selected space.
+
+By default, the table of contents shows a list of [pages, links, and groups](../creating-content/content-structure/page.md#organizing-your-content) that make up a space. You’ll find it to the right of the sidebar. It’s specific to the space you’re currently viewing.
+
+The table of contents is also where you can view and manage [resuable content](../creating-content/reusable-content.md) and [files](../creating-content/blocks/insert-files.md) for your space.
+
+From the **Pages** tab in the table of contents you can:
+
+* Create new [pages](gitbook-ui.md#pages) and subpages
+* Create [page groups](gitbook-ui.md#groups)
+* Add [external links](gitbook-ui.md#external-links)
+* Access [the Actions menu](gitbook-ui.md#the-actions-menu)\
+
+
+
+
+ \
+ for individual pages.
+
+In the **Reusable content** tab, you can:
+
+* View and search through the reusable content in the space
+* Create new reusable content
+* Drag and drop reusable content onto the page
+* Rename and delete reusable content
+
+In the **Files** tab, you can:
+
+* View, search and reorder the files in your space
+* Drag and drop more files into your space
+* Manage individual files
+
+If you want to give more focus to the content of your page, you can temporarily hide the table of contents by hovering your cursor next to it and clicking the **Hide** button that appears. To make it appear again, hover your cursor near the edge of the page and click the **Show** button .
+
+### Space header
+
+
The space header sits at the top of the editor, and offers options that apply to the whole space.
+
+The space header contains information about the space you’re currently viewing. It lets you do things like publish and share your space, view the comments and history for the space, configure [GitHub or GitLab sync](../getting-started/git-sync/), and more.
+
+{% hint style="info" %}
+The space header is adaptable, and changes depending on the space and mode you’re currently in.
+
+For example, if you’re editing a [change request](../collaboration/change-requests.md), you will see options to open the editor, view changes and merge your change request. If you’re viewing a read-only space, you will have the option to open a new change request, but won’t have an editor option.
+{% endhint %}
+
+The space header includes:
+
+* **The space emoji or icon**\
+ You can choose an emoji or icon for your space, to help you easily identify it in the sidebar.
+* **The space name**\
+ The name of the space that will appear in the sidebar, and your documentation if and when you choose to publish it.
+* **The space’s breadcrumbs**\
+ A full, linear list of the collections or docs sites the space lives in.
+* **Actions menu** \
+ Offers a list of actions for your space. Similar to [page actions](gitbook-ui.md#the-actions-menu), the available actions for a space will differ depending on the mode you’re currently in.
+* **Editor view**\
+ This view is where you can make edits to your content using GitBook’s block-based editor.
+* **Changes view**\
+ This view [highlights the changes](../collaboration/change-requests.md#diff-mode) made within a change request using the diff view. This is ideal for reviewing new content before merging your change request to push the changes live.
+* **Preview**\
+ This view allows you to quickly see a preview of your content before you merge a change request.
+* **Collaborators**\
+ The avatar of anyone else who’s currently viewing a page in your space, with colored circles to show their cursor color. Click an avatar to jump to the page they’re currently viewing.
+* **Git Sync configuration**\
+ The [GitHub and GitLab Sync](../getting-started/git-sync/) configuration for your space.
+* **The Share menu**\
+ Allows you to publish and share your space. You can also invite others to [collaborate](../content-editor/editor/broken-reference/) through this menu.
+* **Comments**\
+ See the [comments and discussions](../collaboration/comments.md) you and your team have had about the space content.
+* **Broken links**\
+ Any [broken links](../creating-content/broken-links.md) that have been found in the current space or change request.
+* **Change requests**\
+ Create, update, and delete [change requests](../collaboration/change-requests.md) in your space.
+* **Space history**\
+ View [a version history](../creating-content/version-control.md) that includes all the changes made in the space — or in your current change request — over time.
+* **The Edit button**\
+ If your space is published, or someone has locked[ live edits](../collaboration/live-edits.md), the **Edit** button will appear in the space header. It will create a new [change request](../collaboration/change-requests.md) to edit content.
+
+### Site header
+
+The site header contains information about the site you’re currently viewing. It lets you do things like view site insights, customize your site, change its settings and preview the site in different modes and screen sizes. You can also configure integrations and manage members’ access.
+
+The site header includes:
+
+* **The site name**\
+ The name of the space that will appear in the sidebar, and your documentation if and when you choose to publish it.
+* **The site’s breadcrumbs**\
+ A link back to the main Docs sites screen.
+* **Actions menu** Offers a list of actions for your site. You can visit your site or copy its URL quickly from this menu
+* **Overview**\
+ The site overview shows you essential information about your site including it’s URL, publish status, audience and content, as well as top-level insights.
+* **Insights**\
+ The [insights panel](../publishing-documentation/insights.md) gives you detailed anayltics about your site and how it’s performing.
+* **Customization**\
+ Here you can [customize your site](../publishing-documentation/customization/) with your own logo, colors, header links, and much more.
+* **Settings**\
+ Access your [site’s settings](../publishing-documentation/site-settings.md) and control the name, audience, content structure and other options.
+* **Preview**\
+ The preview tab lets you quickly see how your published site will look in light and dark mode across desktop and mobile displays.
+* **Integrations**\
+ The button opens a modal that lets you install and configure [integrations](../integrations/install-an-integration.md) for your site.
+* **Member access**\
+ View and manage who can access your site in the GitBook app, and what permissions they have.
+* **Visit site**\
+ Click this to instantly open your published docs site in a new tab. This button only appears when your site is live.
+
+### Content editor
+
+The editor is the main part of your space, where you can write or insert content in GitBook.
+
+In addition to the multiple [content blocks](../creating-content/blocks/) you can insert, you can also [embed content](../creating-content/blocks/embed-a-url.md) and use certain [integrations](broken-reference/).
+
+### Page title and description
+
+At the top of each page you can set a **title**, add an optional **emoji**, and write a **description**. The title you use will appear in the table of contents, and forms your page’s URL slug when published.
+
+Your page description can be a maximum of 200 characters long, and will act as the preview text for your page in search engines.
+
+{% hint style="info" %}
+You can change the URL slug for a page by choosing **Page Actions** > **Rename**. Find out more about [Page Actions](gitbook-ui.md#page-options) below.
+{% endhint %}
+
+### Page actions menu
+
+The page’s **Actions menu** allows you to do things like duplicate, rename or delete your page.
+
+You can open the **Actions menu** using the icon that appears when hovering over your page in the sidebar, or from the icon next to the page title.
+
+{% hint style="info" %}
+The type of actions available will depend on whether you’re in [live editing](../collaboration/live-edits.md) mode or a [change request](../collaboration/change-requests.md).
+{% endhint %}
+
+### Page options
+
+
The Page options side panel offers customization options for your documentation and navigation.
+
+With page options, you cam customize your documentation layout and navigation. You can only access page options if you’re in an editing mode.
+
+You can open the **Page options** side panel by opening the page’s **Action menu** and choosing **Options**, or by hovering over the main title of the page and clicking **Page options** when it appears.
+
+{% hint style="info" %}
+Certain changes, such as disabling the table of content, only apply to published documentation and may not be visible in the editor.
+{% endhint %}
+
+### Page outline
+
+
The page outline shows H1 and H2 headings, allowing you to quickly jump to a specific section on an individual page.
+
+The **page outline** sits on the right-hand side of the editor, and makes it easy to jump directly to the section of the page you’re looking for.
+
+Any [headings](../creating-content/blocks/heading.md) you add to the page will appear in the page outline listed here.
+
+The page outline will appear in your published site, too. You can toggle it on or off in the [**Page options**](gitbook-ui.md#page-options) side panel.
+
+{% hint style="info" %}
+If you can’t see the right-hand column of the app, it may be because your browser window is less than 1430 pixels wide. Your browser window needs to be at least 1430 pixels wide to see and use the page outline.
+{% endhint %}
diff --git a/resources/glossary.md b/resources/glossary.md
new file mode 100644
index 00000000..d9b009cb
--- /dev/null
+++ b/resources/glossary.md
@@ -0,0 +1,121 @@
+---
+icon: book-open
+---
+
+# Glossary
+
+### A
+
+**Actions menu:** The menu that opens when you click the three dots next to a page or item in the GitBook interface. The Actions menu may show different options depending on your current view mode.
+
+**Add new:** The button/menu at the bottom of a space’s table of contents that lets you add new content to your space. Also used to refer to the **+** buttons next to the **Docs sites** and **Spaces** section headers in the sidebar, which you can click to create a new site, space or collection.
+
+**Ask or search:** The search tool for content in GitBook. You can click at the top of the sidebar to open it, or press **⌘ + K**. You can type a keyword for a standard search, or ask a question using GitBook AI, which will summarize a result based on your content.
+
+**audience settings:** The settings that decide who can access a published docs site. See [publish-a-docs-site](../publishing-documentation/publish-a-docs-site/ "mention") for more information about the options in the **Audience settings menu**.
+
+### B
+
+**block:** Every piece of content you add to a page exists in a block. There are many different types of block, allowing you to add text, images, tables, code, API references, embedded content and much more. You can move a block around by dragging it, change its settings, and in some cases change a block to be a different type, from the block’s [Options menu](glossary.md#o).
+
+### C
+
+**change request:** Change requests are similar to pull requests in GitHub. They let you work on multiple branches of the same space in parallel — while keeping the original version intact. In GitBook you can create a new change request and make edits to a space, then submit your changes for review. Those changes won’t appear in the primary space until someone merges that change request.
+
+**collection:** A group of spaces. You can think of collections like a folder for your spaces.
+
+**context menu:** The menu that appears above highlighted text in the editor. You can use it to format your text in a number of ways, including bold, italic, and code, or add links or annotations to your copy.
+
+**Comments:** A side panel that lets you add a comment to any block on a page. You can reply to comments to create a [discussion](glossary.md#d), tag people using @ and add emojis to your comments. You can also react to comments with an emoji, resolve comments that are no longer relevant, and filter to view just the comments you need.
+
+**cover:** An image that sits at the top of a page. You can add a cover to any page, and set it to span the full width of your page, or just the width of your content as a hero image. See [#page-covers](../creating-content/content-structure/page.md#page-covers "mention") to find out more.
+
+**custom domain:** A customized URL that you can set up for a docs site, e.g. docs.yourcompany.com. You can configure it in the **Settings** panel for your docs site. See [custom-domain.md](../publishing-documentation/custom-domain.md "mention") to find out more.
+
+### D
+
+**diff view:** A toggle that highlight which pages and blocks have been added, edited or deleted within a change request. You can toggle it on using the **View changes** button in the [space header](glossary.md#s).
+
+**discussions:** When you reply to a comment you create a discussion — effectively a threaded conversation within the Comments side panel.
+
+**docs site:** A published site containing the information written in the GitBook editor. Docs sites are accessible to users without a GitBook account.
+
+**domain:** The base of a docs site’s URL. You can customize this from the **Domains** section in your site’s **Settings** page. [Setting a custom domain](../publishing-documentation/custom-domain.md) will override this setting.
+
+### E
+
+**editor:** The GitBook UI that you see when you log into the app. GitBook’s block-based editor offers Markdown support and WYSIWYG editing tools, and you can add and move [blocks](glossary.md#b) around on the page.
+
+### F
+
+**files:** Images, videos and other items that you can upload to a space. You can view and manage your files by opening the **Files** tab at the top of the table of contents on the left of your content
+
+### G
+
+**Git Sync:** [Git Sync](../getting-started/git-sync/) lets you synchronize GitHub or GitLab repositories with GitBook and turn Markdown files into documentation. It’s a two-way sync, so changes you make in GitBook appear in your repo, and changes you make directly in GitHub or GitLab will update in GitBook. You can set up Git Sync by adding the GitHub Sync or GitLab sync integrations to your organization. Find out more
+
+**GitBook AI:** An AI assistant that is trained on your knowledge base and documentation to [answer questions](../creating-content/searching-your-content/gitbook-ai.md). You can ask GitBook AI anything about your documentation from the **Ask or search** menu. You can also ask GitBook AI to help you [write or edit your content](../creating-content/write-and-edit-with-ai.md) in the editor.
+
+### I
+
+**inline palette:** Type `/` when **in the middle of a block** in the [editor](glossary.md#e) to open the inline palette. It lets you quickly add different kinds of inline content to your block, from images and emojis to Math & TeX.
+
+**insert palette:** Type `/` in **an empty block** to open the insert palette. It shows all the available blocks you can create, including plugins and reusable content. You can search for a block to narrow the selection, and select with your keyboard or cursor.
+
+**insights:** GitBook’s built in analytics tools for docs sites that let you see page views, feedback and popular searches on your published spaces.
+
+**integrations:** GitBook integrations let you connect your GitBook spaces to third party services and platforms. You can install integrations in any space in your organization from the Integrations menu.
+
+### L
+
+**live edits:** The ability to make changes to a live version of a document, without creating a change request. This is the default option for unpublished GitBook spaces.
+
+**locked live edits:** When you lock live edits, people will need to create a change request in order to make changes to a document in GitBook. This helps avoid mistakes and maintain good working practices for important documents. You can lock live edits for any space — and it is automatically enabled for published spaces.
+
+### **M**
+
+**member management:** Tools that allow you to view and edit the members in your organization, including their admin rights and the spaces they have access to.
+
+### O
+
+**Options menu:** The menu that opens when you click the six dots next to a block. Here you can change the appearance of a block. Click and drag on the six dots to move the block around the page.
+
+### P
+
+**page:** A place where you can add or write your content using blocks. Pages live inside a [space](glossary.md#s), and you can give every page a title and an optional icon or emoji.
+
+**page group:** A way to group pages together. You can set a name and an optional icon or emoji for each page group.
+
+**page options:** A collection of options that you can set for your pages using the **Page options** side panel. You can select a layout preset, or control individual options such as hiding the page title and description, table of contents or page outline. Find out more in [#page-options](../creating-content/content-structure/page.md#page-options "mention").
+
+### R
+
+**reusable content:** Content that is synced across multiple locations in a space. When you create [reusable content](../creating-content/reusable-content.md) you can add it to a space as many times as you need, then edit all those instances at the same time. You can view and manage a space’s reusable content from the **Reusable content** tab at the top of the [table of contents](glossary.md#t).
+
+### S
+
+**sidebar:** The area on the far left of your GitBook window. It contains the **Ask or search** bar, all your docs sites, spaces and collections, as well as things like notifications, integrations and settings.
+
+**site section:** If you want your docs site to act more like a content hub, you can publish multiple spaces to the same docs site as [site sections](../publishing-documentation/site-structure/site-sections.md). These site sections will appear in a tab bar at the top of your published docs, allowing users to switch between content. You can set up site sections in the **Structure** section of **Site settings**.
+
+**slug:** The customizable final part of a URL, usually after the domain and a /. In a docs site, this is inferred from the title of the site, and comes after the domain. You can customize this further if needed from the **Domains** section of **Site settings**.
+
+**space:** An area where you can organize related content. It may contain a single page or multiple pages, sub-pages and page groups.
+
+**space header:** The menu bar below the space overview when you view a space. It contains the space title and icon, as well as buttons to view comments, broken links and change requests, as well as the **Edit in change request** button.
+
+**space overview:** The menu bar at the top of the GitBook app when you view a space. It contains the breadcrumbs for the space you’re in, as well as the [Git Sync](glossary.md#g) configuration button, the Share button, and the [Actions button](glossary.md#a) for the space. If other people are working in the space at the same time as you, you’ll also see their avatars here.
+
+**subpage:** A page that’s nested within another page, typically containing related content.
+
+### T
+
+**table of contents:** The list of document pages, links, and groups that make up a space. You’ll find it on the left of your page, next to the sidebar. The table of content (TOC) also lets you access the space’s [reusable content](glossary.md#r) and [files](glossary.md#f). You can collapse it by hovering near the top right of the TOC.
+
+### V
+
+**variant**: A [variant](../publishing-documentation/site-structure/variants.md) is a different version of your documentation — for example, a translated version of your docs, or docs for a different version number of your product. Site readers can move between different variants using a drop-down menu on the published site.
+
+**version:** A saved snapshot of your space at a specific time. You can access previous versions of your space in the **Version history** menu.
+
+**Version history:** A menu showing major events for a space — such as its creation date, any change requests that you have merged, and any time someone rolled back to a previous version. You can click any version to see how the space looked at that time, and roll back to a previous version if needed.
diff --git a/resources/keyboard-shortcuts.md b/resources/keyboard-shortcuts.md
new file mode 100644
index 00000000..1c4529d8
--- /dev/null
+++ b/resources/keyboard-shortcuts.md
@@ -0,0 +1,26 @@
+---
+description: A quick reference guide to all the keyboard shortcuts available in GitBook
+icon: keyboard
+---
+
+# Keyboard shortcuts
+
+Shortcut keys allow easy and quick methods for navigating or editing content.
+
+## In published documentation
+
+
Description
Mac
Windows
Open the Ask or search panel
⌘+K
Ctrl+K
Open the GitBook Assistant chat window
⌘+I
Ctrl+I
Close the Ask or search or GitBook Assistant panel
Esc
Esc
+
+
+
+## In the GitBook app
+
+
Description
Mac
Windows
Copy
⌘+C
Ctrl+C
Paste
⌘+V
Ctrl+V
Paste as text, without formatting
⌘+Shift+V
Ctrl+Shift+V
Undo
⌘+Z
Ctrl+Z
Redo
⌘+Shift+Z
Ctrl+Shift+Z
Exit from content block (code, tabs, table, quote ...)
diff --git a/reusable-content/overview.md b/reusable-content/overview.md
deleted file mode 100644
index f0e0e0c1..00000000
--- a/reusable-content/overview.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-icon: repeat
----
-
-# Overview
-
-{% hint style="info" %}
-This feature is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-Reusable content lets you sync content across multiple pages in a GitBook space, so you can edit all instances of the block at the same time.
-
-{% hint style="warning" %}
-Reusable content is currently scoped to a single space. We are working on an improvement to allow access to reusable content across your organization. Duplicating a space will not duplicate its reusable content.
-{% endhint %}
-
-### **How to create reusable content**
-
-To create reusable content, [select one or more blocks](../content-editor/blocks/#selecting-blocks-and-interacting-with-selected-blocks), then open the **Action menu** and choose **Turn into reusable content**. You can also give your block a name to make it easier to find and reuse later.
-
-Alternatively, you can select one or more blocks and then hit **Cmd+C** to open a prompt asking if you want to create reusable content.
-
-
-
-### **Inserting reusable content**
-
-You can insert reusable content as you would with any other block. Hit `/` on an empty line to open the **Insert palette** and search for your content by its name or simply searching "reusable". Alternatively, click the `+` on the left of any block or empty line.
-
-You can choose the content you want to add from the list, or search for the one you need.
-
-You will also find the reusable content panel in the pages sidebar, where you can find a list of previously created content blocks.
-
-### **Editing reusable content**
-
-Reusable content is like any other content - you can edit it directly or through change requests. Your edits will be synced everywhere the content is used.
-
-If you're making changes inside a change request, the content will be synced everywhere once that change request is merged.
-
-### **Detach reusable content**
-
-You can detach reusable content by opening the **Action menu** and selecting **Detach**. Detaching will convert the content back to regular blocks.
-
-Once detached, any changes you make to the block(s) will not be reflected across the other instances, and changes you make in those instances will not be reflected in the detached block(s). Other instances of the reusable content remain synced together.
-
-### Delete reusable content
-
-You can delete reusable content from the page's table of contents. Select the **Action menu** next to the content you’d like to delete, and select **Delete**.
-
-Deleting reusable content will **delete it from all pages it is used in**. This action cannot be undone.
-
-
-
-## Reusable content and syncing with GitHub & GitLab
-
-Reusable content is fully supported when syncing to GitHub & GitLab. Your reusable content will be exported to a dedicated `includes` folder, each content being a separate Markdown file.
-
-Your content is then referenced in your other pages using the `include` directive.
-
diff --git a/snippets/overview.md b/snippets/overview.md
index eb7797d6..1b10dc87 100644
--- a/snippets/overview.md
+++ b/snippets/overview.md
@@ -2,14 +2,19 @@
description: >-
Curate knowledge from your favorite tools — and seamlessly keep your GitBook
content up to date
+noIndex: true
icon: bullseye-arrow
---
# Overview
+{% hint style="warning" %}
+The Snippets feature is no longer maintained in GitBook and is subject to change. We recommend to structure your content in a [space](../creating-content/content-structure/space.md) instead.
+{% endhint %}
+
Technical knowledge is best when it’s accessible, and shared. In GitBook, snippets make it easy to collect knowledge from your favorite tools, while content insights help you keep your content up to date effortlessly.
### Learn more about
-
Snippets (beta)
Effortlessly add structured, accessible information to your knowledge base, directly from your favorite tools.
diff --git a/snippets/snippets-beta.md b/snippets/snippets-beta.md
index 9781d649..8f6ea56f 100644
--- a/snippets/snippets-beta.md
+++ b/snippets/snippets-beta.md
@@ -1,21 +1,26 @@
---
-icon: scissors
description: >-
Add snippets of knowledge from your favorite tools, and GitBook AI will turn
them into something useful
+noIndex: true
+icon: scissors
---
# Snippets (beta)
+{% hint style="warning" %}
+The Snippets feature is no longer maintained in GitBook and is subject to change. We recommend to structure your content in a [space](../creating-content/content-structure/space.md) instead.
+{% endhint %}
+
{% hint style="info" %}
This feature is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
{% endhint %}
In GitBook, you can capture unstructured information using [integrations](broken-reference), and GitBook AI will turn it into a **snippet** — a structured page of information that’s easy to read and digest. You can also create snippets manually within the app.
-GitBook will index all of your snippets alongside the rest of your content and can reference them when you or your team [searches for information](../content-editor/searching-your-content/). You can also merge snippets into existing docs or content to keep everything up to date.
+GitBook will index all of your snippets alongside the rest of your content and can reference them when you or your team [searches for information](../creating-content/searching-your-content/). You can also merge snippets into existing docs or content to keep everything up to date.
-
The Snippets page holds all of your snippets in one place and makes it easy to connect integrations so you can add more.
+
The Snippets page holds all of your snippets in one place and makes it easy to connect integrations so you can add more.
### Product Demo
@@ -41,7 +46,7 @@ You can create a snippet manually from the **Snippets** page, by clicking the **
You can edit a snippet you’ve captured by clicking to open it from the **Snippets** page. This will open an editor view, where you can edit any information that might be wrong, or add additional context for things that might be missing.
-
You can edit a snippet directly in the editor by opening it.
+
You can edit a snippet directly in the editor by opening it.
### Share a snippet
@@ -51,15 +56,15 @@ You can share a snippet with others as a direct link to the organization it’s
You can convert a snippet to a full page within your documentation. To do this, open a snippet and choose **Convert to page** in the top-right corner.
-You’ll be prompted to choose a space for your page — you can use the drop-down menu to search for a space or scroll. When you select a space, GitBook will add the content of the snippet as a new page, or [open a change request](../collaboration/change-requests.md) if you select a space [with locked live edits](../content-editor/editing-content/live-edits.md).
+You’ll be prompted to choose a space for your page — you can use the drop-down menu to search for a space or scroll. When you select a space, GitBook will add the content of the snippet as a new page, or [open a change request](../collaboration/change-requests.md) if you select a space [with locked live edits](../collaboration/live-edits.md).
{% hint style="info" %}
-**Note:** When you convert a snippet to the page, GitBook will automatically archive the snippet. If you’ve linked to the snippet using [an inline link](../content-editor/editing-content/inline.md#links) or [a snippet block](../content-editor/blocks/snippets.md), the links will still work but will take readers to the original snippet, not the new page.
+**Note:** When you convert a snippet to the page, GitBook will automatically archive the snippet. If you’ve linked to the snippet using [an inline link](../creating-content/formatting/inline.md#links) or [a snippet block](../creating-content/blocks/snippets.md), the links will still work but will take readers to the original snippet, not the new page.
{% endhint %}
### Delete a snippet
-To delete a snippet, open it by clicking it in the **Snippets** page, then click the **Discard** option from the Action menu in the upper right corner.
+To delete a snippet, open it by clicking it in the **Snippets** page, then click the **Discard** option from the Action menu in the upper right corner.
{% hint style="warning" %}
A snippet is permanently deleted when you discard it.
+ 
+ 
+
+
icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
+1. Go to the organization’s settings page. You can click on the settings 
icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
+ icon at the bottom of the sidebar and then click on **\[organization name] settings** to get there.
2. Click on the **billing** tab. This will take you to a billing page hosted on Stripe, our payment processor.
3. Click the **cancel plan** button.
4. On the following page, confirm by clicking a second button labelled **cancel plan**.
@@ -22,8 +22,8 @@ If your mind is made up, here’s how to cancel your plan:
Once your plan has been cancelled, as per our [billing policy](plans/billing-policy.md), it will remain active until the end of your current billing period. Your subscription will no longer renew, and the plan’s cancellation will take full effect at the end of that billing period.
{% endhint %}
-### Changed your mind? No problem!
+### Change your mind?
After cancelling and before the end of your current billing period, you have the option to renew your plan! Just click the **renew plan** button shown below (and again on the next page to confirm) and your subscription will once again renew automatically.
-Or, if you change your mind _after_ the end of the billing period, you can purchase a new plan.
+After this, if you’d like to use GitBook again on a paid plan, you can purchase a new plan.
diff --git a/account-management/member-management/README.md b/account-management/member-management/README.md
index 8117cbc9..caf7e119 100644
--- a/account-management/member-management/README.md
+++ b/account-management/member-management/README.md
@@ -7,29 +7,12 @@ description: Learn how to manage access to content for members of your organizat
You can [invite and remove members](invite-members-to-your-organization.md) from your organization, manage members’ content access through [roles](roles.md), and manage [teams](teams.md) of members from the members’ page in your organization’s settings.
-{% hint style="info" %}
-**Permissions**
-
-**Admins** can invite and remove members, change members’ roles, and manage teams. **Creators** can manage permissions at a content level (collection or space).\
-**Team owners** can manage members of the team they have ownership of.
-{% endhint %}
-
-{% embed url="https://www.youtube.com/watch?v=XdocAjHKuLU" %}
-
## Members & permissions
-Shows each person’s role, last seen date, and [SSO](../sso-and-saml/sso-and-saml.md) status, if applicable. You’ll also see an overview of the [spaces](../../content-editor/editor/content-structure/what-is-a-space.md) they can access and, if you’re on the Pro plan, how many [teams](teams.md) they’re part of.
-
-
.png)
.png)
.png)
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.svg)
in the top-right corner of the window and choose **Archive**. You can find and reopen archived change requests later by opening the **Change Requests** menu and selecting the **Archived** tab.
+To archive a change request, first open it up. Then click the **Actions menu** 
next to the page title.
-2. Select **Export to PDF > Current page**.
-3. Wait for the page to load, then click the **Print or save as PDF** button in the upper right to open your browsers Print menu.
-4. From here, you can save the page as a PDF or open it in your PDF viewer using the typical process for your browser.
-
-
.png)
icon next to your block and select full width
-
-
.png)
next to the block. [Read more about full-width blocks.](./#new-full-width-blocks)
-{% endhint %}
-
-#### Please also check:
-
-{% content-ref url="openapi.md" %}
-[openapi.md](openapi.md)
-{% endcontent-ref %}
-
-## Representation in Markdown
-
-```
-# API
-
-{% raw %}
-{% swagger method="get" path="" baseUrl="" summary="" %}
-{% swagger-description %}
-
-{% endswagger-description %}
-{% endswagger %}
-{% endraw %}
-```
diff --git a/content-creation/blocks/cards.md b/content-creation/blocks/cards.md
deleted file mode 100644
index e28d8f2a..00000000
--- a/content-creation/blocks/cards.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-description: Card content block
----
-
-# Cards
-
-Cards allow you to create a new visually pleasing page layout with text and images. They can be used to build landing pages or display any other content in a non-linear way.
-
-You can select large or medium-sized cards and link them to the relevant resources.
-
-### Example of a card
-
-.png)
\
-you can add and format text. You can also add additional columns such as numbers, user or rating.
-
-#### Adding links and images to your cards
-
-By clicking on the 
symbol you can add a target link (recommended), add [cover images](#user-content-fn-1)[^1] or delete the card completely.
-
-{% hint style="success" %}
-When creating cards, we recommend you use **target links instead of hyperlinks**. Target links will ensure that the reader is redirected to the intended destination, regardless of where they click within the card.
-{% endhint %}
-
-The key to great looking cards is editing your images so that they have the same ratio. For example:
-
-- 16:9 (eg. 1920px x 1080px)
-- 4:3 (eg. 1024X768)
-- 1:1 (eg. 500px x 500px)
-
-By using the same ratio for all of your images you can ensure that they will align when displayed on the page. This means that titles and text under images is also aligned, which provides a better reading experience.
-
-#### Card size
-
-You can select the card size by clicking on
-
diff --git a/content-creation/blocks/embed-a-url.md b/content-creation/blocks/embed-a-url.md
deleted file mode 100644
index 9e2f15fc..00000000
--- a/content-creation/blocks/embed-a-url.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-description: Embed a URL content block
----
-
-# Embed a URL
-
-To add a rich embed, simply paste the link of the content you want to embed and press the enter key! ✨ Note that the content you wish to embed must be publically available in order for GitBook to access the file. For example, when embedding a Google doc the share link that you paste into GitBook must be set to ’Anyone with the link’.
-
-
image
-
-This is a second line
-{% endhint %}
-
-### Representation in Markdown
-
-```markdown
-{% raw %}
-{% 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" %}
-
-### This is a heading
-
-This is a line
-
-This is an inline 
image
-
-This is a second line
-{% endhint %}
-{% endraw %}
-```
diff --git a/content-creation/blocks/insert-files.md b/content-creation/blocks/insert-files.md
deleted file mode 100644
index 27fd31aa..00000000
--- a/content-creation/blocks/insert-files.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-description: Insert files content block
----
-
-# Insert files
-
-You can upload file assets to your GitBook space and include them in your spaces for download.
-
-### Example of file
-
-{% file src="../../../.gitbook/assets/hello-world.pdf" %}
-Hello world
-{% endfile %}
-
-### Related
-
-If you are looking to embed external content into your pages, take a look at how to [embed a URL](embed-a-url.md).
-
-## Uploading a file
-
-Files are managed in the files panel of your space. To access the files panel, click on files in the [space sub-navigation](https://docs.gitbook.com/getting-started/overview#space-sub-navigation).
-
-To upload a file, select **browse files** and use your system file dialog to select the file you want to upload.
-
-Files can also be uploaded as part of the image block setup flow, and the OpenAPI block setup flow. Upon creation, each of these blocks will open the files panel and have you either select or upload a new file.
-
-{% hint style="info" %}
-You can drag images from your file system directly into the editor, or paste a copied image into your content, and they will also appear in the files menu for the respective space.
-{% endhint %}
-
-## Managing files
-
-You can search for, rename, or delete files in your space in the files panel of your space. Below the file upload section, you’ll find the file listing. Each file has an action menu that lets you download, replace, rename, or delete your file. At the top of the file listing section, there is a search box, where you can search for your file by its name, and a sort toggle, which will let you sort your files by the date they were last modified, or their size.
-
-
.png)
- 
.png)
next to your block and select **Full width**. This feature is available for the following block types:
-
-* Code Blocks
-* Image blocks
-* Tables
-* Cards
-* API Blocks
-* Integration blocks
-
-#### Example of a full-width table block
-
-.svg)
-
-### Draw with GitBook AI
-
-{% hint style="warning" %}
-GitBook AI is available as part of the Pro plan and Enterprise plan. To find out more, [visit our pricing page](https://www.gitbook.com/pricing).
-{% endhint %}
-
-When using drawing block, you can ask GitBook AI to generate an illustration by specifying a prompt. Simply type in a prompt and hit **Generate**, or choose one of the suggested prompts to get started.
-
-Once GitBook AI has finished the drawing, you can double-click to open the full drawing palette and edit it however you like.
-
-When editing a drawing, click the **Use AI to generate** button to bring up GitBook AI’s prompt editor again and generate a new drawing.
diff --git a/content-editor/blocks/embed-a-url.md b/content-editor/blocks/embed-a-url.md
deleted file mode 100644
index c6223fbc..00000000
--- a/content-editor/blocks/embed-a-url.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-description: "Embed content directly into your page with a URL —\_including videos, music and interactive blocks."
----
-
-# Embedded URLs
-
-To add an embedbed URL, simply paste the link of the content you want to embed and hit `Enter`!
-
-{% hint style="info" %}
-**Note:** The content you want to embed must be publicly available in order for GitBook to access the file. For example, when embedding a Google doc the share settings must be set to _Anyone with the link_.
-{% endhint %}
-
-Here are a few examples of the kind of content you can embed into GitBook — and there are many more!
-
-### Videos
-
-{% hint style="info" %}
-**Note:** You can choose to auto-play and loop videos that you embed into GitBook by adding `?autoplay=1&_loop=1` to the end of your video’s URL
-{% endhint %}
-
-{% embed url="https://www.youtube.com/watch?v=D_uLM5i0Z4c" %}
-
-### Codepen
-
-{% embed url="https://codepen.io/davidkpiano/pen/wMqXea" %}
-
-### Spotify
-
-{% embed url="https://open.spotify.com/track/4FmiciU3ZmfgABlbCSXcWw?si=65zMAhStT2ivTit-kZISWg" %}
-
-### Representation in Markdown
-
-```markdown
-{% raw %}
-{% embed url="URL_HERE" %}
-{% endraw %}
-```
diff --git a/content-editor/blocks/heading.md b/content-editor/blocks/heading.md
deleted file mode 100644
index cff4c5d8..00000000
--- a/content-editor/blocks/heading.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-description: Add heading blocks to a page to organize your content and improve SEO.
----
-
-# Headings
-
-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](../editor/navigation.md#page-outline).
-
-{% hint style="info" %}
-Reading on a screen is less comfortable than reading on paper. Sometimes splitting longer content into different [pages](../editor/content-structure/content-in-a-space.md) can help with overall readability.
-{% endhint %}
-
-### 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 GitBook space, you can use a [relative link](../editing-content/inline.md#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** 
-
-
- 
and toggling **Hide page**.
-
-Hidden pages will still be indexable by search and GitBook AI, but will not appear in the table of contents in your published site. Hidden pages will still be accessible through direct links.
-
-If hidden the following will appear in the front matter of the markdown file when using Git Sync:
-
-.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
that appears. To make it appear again, hover your cursor near the edge of the page and click the **Show** button 
.
-
-### Space overview & space header
-
-
.png){kind=link}
.png){kind=link}
+
+### Draw with GitBook AI
+
+{% include "../../.gitbook/includes/pro-and-enterprise-hint.md" %}
+
+When using drawing block, you can ask GitBook AI to generate an illustration by specifying a prompt. Simply type in a prompt and hit **Generate**, or choose one of the suggested prompts to get started.
+
+Once GitBook AI has finished the drawing, you can double-click to open the full drawing palette and edit it however you like.
+
+When editing a drawing, click the **Use AI to generate** button to bring up GitBook AI’s prompt editor again and generate a new drawing.
+
+### Representation in Markdown
+
+```markdown
+
+```
diff --git a/creating-content/blocks/embed-a-url.md b/creating-content/blocks/embed-a-url.md
new file mode 100644
index 00000000..6bcf6383
--- /dev/null
+++ b/creating-content/blocks/embed-a-url.md
@@ -0,0 +1,33 @@
+---
+description: Embed videos, music and more directly into your page with a URL
+---
+
+# Embedded URLs
+
+To add an embedbed URL, simply paste the link of the content you want to embed and hit `Enter`.
+
+{% hint style="info" %}
+**Note:** The content you want to embed must be publicly available in order for GitBook to access the file. For example, when embedding a Google doc the share settings must be set to _Anyone with the link_.
+{% endhint %}
+
+### Videos
+
+{% embed url="https://www.youtube.com/watch?v=D_uLM5i0Z4c" %}
+
+{% 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 %}
+
+### Codepen
+
+{% embed url="https://codepen.io/davidkpiano/pen/wMqXea" %}
+
+### Spotify
+
+{% embed url="https://open.spotify.com/track/4FmiciU3ZmfgABlbCSXcWw?si=65zMAhStT2ivTit-kZISWg" %}
+
+### Representation in Markdown
+
+```markdown
+{% embed url="URL_HERE" %}
+```
diff --git a/content-editor/blocks/expandable.md b/creating-content/blocks/expandable.md
similarity index 100%
rename from content-editor/blocks/expandable.md
rename to creating-content/blocks/expandable.md
diff --git a/creating-content/blocks/heading.md b/creating-content/blocks/heading.md
new file mode 100644
index 00000000..5782d146
--- /dev/null
+++ b/creating-content/blocks/heading.md
@@ -0,0 +1,52 @@
+---
+description: Add heading blocks to a page to organize your content and improve SEO
+---
+
+# Headings
+
+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](../../resources/gitbook-ui.md#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 GitBook space, you can use a [relative link](../formatting/inline.md#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** 
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" %}
+
+## This is a H2 heading
+
+This is a line
+
+This is an inline 
+```
+{% endcode %}
+
+### 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:
+:car:
+:dog:
+```
+{% endcode %}
+
+### Links
+
+You can insert three different types of links:
+
+* [Relative links](inline.md#relative-links)
+* [Absolute links](inline.md#absolute-links)
+* [Email address `mailto` links](inline.md#email-address-mailto-links)
+
+#### Relative links
+
+Relative links are links created by linking to [pages](../content-structure/page.md) that already exist in your space. 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 space](../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
+```
+
+### Math & TeX
+
+Using this option, you can create an inline math formula in your content, like this: $$f(x) = x * e^{2 pi i \xi x}$$. 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](../blocks/math-and-tex.md) by opening the command palette in an empty block and choosing the second Math & TeX option.
+{% endhint %}
+
+#### Representation in Markdown
+
+```markdown
+# Math and TeX block
+
+$$f(x) = x * e^{2 pi i \xi x}$$
+```
+
+### Buttons
+
+Buttons are a great way to describe calls to action. You can use them to send users to other pages in GitBook, or to external URLs.
+
+Buttons have both primary and secondary styles. Here are a couple of examples:
+
+Sign up to GitBook Go to top
+
+#### Representation in Markdown
+
+```markdown
+GitBook
+```
+
+### Icons
+
+Icons allow you to add extra visual indications to your site. You can add them inline to paragraphs, inside a card, or anywhere else you need to add some flair. They will use the visual style defined in your [customization settings](../../publishing-documentation/customization/icons-colors-and-themes.md).
+
+:facebook: :github: :x-twitter: :instagram:
+
+Visit [Font Awesome](https://fontawesome.com/) to explore the different icons available.
+
+#### Representation in Markdown
+
+```markdown
+:github:
+```
+
+### Expressions
+
+Expressions allow you to dynamically display content defined in a [variable](../variables-and-expressions.md). Expressions can be inserted from the `/` menu. Once inserted, double 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.
diff --git a/creating-content/formatting/markdown.md b/creating-content/formatting/markdown.md
new file mode 100644
index 00000000..0a21be37
--- /dev/null
+++ b/creating-content/formatting/markdown.md
@@ -0,0 +1,70 @@
+---
+description: >-
+ Write Markdown directly in the editor to easily create content using common
+ syntax
+---
+
+# Markdown
+
+
 the necessary read-only permissions to PRs.
+
+For every PR create using a target branch synced with a GitBook space, you’ll see a status added to the PR with a unique preview URL. Clicking the **Details** link on the status will take you to the preview URL for your content. You can then make sure the content is as expected before merging the PR.
+
+{% hint style=](../../.gitbook/assets/10_01_25_git_sync_preview.svg)
+
+### Be sure to only create readme files in your repo
+
+When Git Sync is enabled, be careful not to create readme files through the GitBook UI. Creating readme files through the GitBook UI:
+
+* Creates duplicate README files in your repository
+* Causes rendering conflicts between GitBook and GitHub
+* May break builds and deployment processes
+* Results in unpredictable file precedence
+
+This includes files named README.md, readme.md, Readme.md, and README (without extension). Instead, remember to manage your README file directly in your git repository.
+
+### Still facing errors?
+
+Make sure that:
+
+* Your repository **has a** `README.md` **file** at its root (or at the `root` folder specified in your `.gitbook.yaml`) that was created directly in your git repository. This file is required and is used as the homepage for your documentation. For more details, refer to our [content configuration](content-configuration.md).
+* If you have YAML frontmatters in your Markdown files, make sure they are valid using a [linter](http://www.yamllint.com).
+
+## GitBook is not using my `docs` folder
+
+By default, GitBook uses the root of the repository as a starting point. A specific directory can be specified to scope the markdown files. Take a look at our documentation on [content configuration](content-configuration.md) for more details.
+
+## GitBook is creating new markdown files
+
+**When synchronizing and editing from GitBook** with an existing Git repository, GitBook may create new markdown files instead of using the existing ones. This is done to ensure GitBook doesn't overrite files that existed in your repository before.
+
+## Redirects aren't working correctly
+
+The YAML file needs to be correctly formatted for the redirects to work. Errors such as incorrect indentation or whitespace can result in your redirects not working. [Validating your YAML file](https://www.yamllint.com/) can ensure that the redirects will work smoothly.
+
+When setting redirects, do not add any leading slashes. For example, trying to redirect to `./misc/support.md` will not work.
+
+It's also important to consider that as long as a page exists for a path, GitBook won’t be looking for a possible redirect. So if you're setting up a redirect for an old page to a new one, you will need to remove the old page in order for the redirect to work.
+
+## My repository is not listed
+
+### For GitHub repositories
+
+Make sure that you have installed the GitBook GitHub app to the correct locations (when installing the app, you can choose to install it to your personal GitHub, or to any organization you have permissions for) and that you have given the app the correct repository permissions.
+
+### For GitLab repositories
+
+Make sure that your access token has been configured with the following access:
+
+* `api`
+* `read_repository`
+* `write_repository`
+
+## Nothing happens on GitBook after adding a new file to my repository
+
+{% hint style="warning" %}
+**This section specifically addresses problems when a `SUMMARY.md` file already exists**
+
+If your repository does not include a `SUMMARY.md` file, GitBook will automatically create one upon the first sync. This means that if you edited your content from GitBook at least once after setting up Git sync, GitBook should have created this file automatically.
+{% endhint %}
+
+If after updating your repository by adding or modifying a markdown file, you do not see the update reflected on GitBook and the sidebar doesn’t indicate an error during the sync, your modified file(s) is probably not listed in [your `SUMMARY.md` file](content-configuration.md#summary).
+
+This could either be because you created the file manually, or because you made an edit on GitBook and the GitBook to Git export phase of the sync created it for you.
+
+The content of this file mirrors your [table of contents](../../resources/gitbook-ui.md#table-of-contents) on GitBook and is used during the Git to GitBook import phase of the sync to recreate your table of contents and re-conciliate upcoming updates from the repository with your existing content on GitBook.
+
+If after ensuring that all your files are included in the `SUMMARY.md` file there’s still nothing happening on GitBook, don’t hesitate to [contact support](https://gitbook.com/docs/help-center/further-help/how-do-i-contact-support) for assistance.
+
+## GitHub preview is not showing
+
+If your GitHub preview is not showing, it might be because your GitSync integration was configured before January 2022. Versions of GitSync configured before this date do not include GitHub Preview.
+
+You should have received a notification requesting you to accept an updated permission request to enable read-only access to PRs.
+
+In case you did not receive the notification, to troubleshoot you need to update to the new version:
+
+1. Uninstall the GitSync integration from your organization.
+2. Reinstall the new version with the updated permissions.
+
+Please note that uninstalling the GitSync integration will require reconfiguring the integration again on any spaces it was previously connected to.
+
+## Potential duplicated accounts when signing in
+
+This error usually occurs when the GitHub account that you use to set up the sync is already associated with a different GitBook user account.
+
+A good way to identify which GitBook account the GitHub account is already linked to is:
+
+1. Log out from your current GitBook user session (i.e. `name@email.com`)
+2. Log out from any GitHub user sessions.
+3. Go to [the Log in page](https://app.gitbook.com/login).
+4. Select the "Sign in with GitHub" option.
+5. Enter your GitHub credentials.
+6. Once logged in, go to [the account settings](https://app.gitbook.com/account) and either:
+ 1. Unlink the account from the "Third-party Login > GitHub" section in the Personal setting
+ 2. Delete the account altogether if you do not need it.
+7. Log out from the session.
+8. Log back in using your `name@email.com` GitBook account.
+9. Try to set up Git Sync again.
diff --git a/getting-started/import.md b/getting-started/import.md
new file mode 100644
index 00000000..82db67d0
--- /dev/null
+++ b/getting-started/import.md
@@ -0,0 +1,98 @@
+---
+description: >-
+ How to import existing content into GitBook from Confluence, Notion, Git and
+ more
+icon: arrow-up-to-line
+---
+
+# Importing content
+
+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.md#import-using-git-sync).
+
+## Using the Import Panel
+
+### Supported import formats
+
+GitBook supports imports from websites or files in the following formats:
+
+* Markdown (`.md` or `.markdown`)
+* HTML (`.html`)
+* Microsoft Word (`.docx`)
+
+We 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.
+
+{% 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
+
+
[GitBook Support](mailto:support@gitbook.com).
diff --git a/help-and-faq/faq/report-bugs.md b/help-and-faq/faq/report-bugs.md
deleted file mode 100644
index 7a78860d..00000000
--- a/help-and-faq/faq/report-bugs.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-description: >-
- Encountered a bug? Find out how to provide all the essential information for
- speedy resolution.
----
-
-# How do I report bugs?
-
-Bugs should be reported using the messaging widget available from your dashboard or by sending an email to [support@gitbook.com](mailto:support@gitbook.com). In order to get the best help possible, please provide as much context on how you encountered the bug.
-
-## **Generate Network Captures for Troubleshooting**
-
-**HAR**
-
-A HAR capture (HTTP Archives) records the requests and responses that your browser makes with the GitBook Application.
-
-### **Chrome**
-
-1. In Chrome, go to the page within GitBook where you are experiencing trouble.
-2. At the top-right of your browser window, click the Chrome menu (⋮).
-3. Select **tools > developer tools**. The developer tools window opens as a docked panel at the side or bottom of Chrome.
-4. Click the **network** tab.
-5. Select **preserve log**.
-6. You will see a red circle at the top left of the Network tab. This means the capture has started. If the circle is black, click the **black circle** to start recording activity in your browser.
-7. **Refresh the page** and reproduce the problem while the capture is running.
-8. After you successfully reproduce the issue, right click on any row of the activity pane and select **Save as HAR with content**.
-9. Select the **console** tab
-10. Right-click anywhere in the console and select **save as...**.
-11. Name the log file **Chrome-console.log**.
-12. Send both files as shared links in a reply to your case.
-
-### **Firefox**
-
-1. In Firefox, go to the page within GitBook where you are experiencing trouble.
-2. Click the Firefox menu (Three horizontal parallel lines) at the top-right of your browser window.
-3. Select **web developer > network**.
-4. The developer tools window opens as a docked panel at the side or bottom of Firefox.
-5. Click the **network** tab.
-6. Select **persist logs**.
-7. **Refresh the page** and reproduce the problem while the capture is running.
-8. After you successfully reproduce the issue, right-click any row of the activity pane and select **Save all as HAR**.
-9. Select the **console** tab.
-10. Right-click any row and select **select all**.
-11. Paste the content in a text file and name it **console-log.txt**.
-12. Send both files as shared links in a reply to your case.
-
-### **Safari**
-
-1. In Safari, go to the page within GitBook where you are experiencing trouble.
-2. In the menu bar at the top, click **develop** and select **show web inspector**.
-3. Click the **console** tab and select **preserve log**.
-4. Go back to the **network** tab.
-5. **Refresh the page** and reproduce the problem while the capture is running.
-6. After you successfully reproduce the issue, right-click any row of the activity pane and select **export HAR**.
-7. Click the **console** tab.
-8. Right-click any row and select **select all**.
-9. Paste the content in a text file and name it **console-log.txt**.
-10. Send both files as shared links in a reply to your case.
-
-### **Internet Explorer (IE11)**
-
-1. In Internet Explorer, go to the page within GitBook where you are experiencing trouble.
-2. Click the gear icon in the top right.
-3. Select **F12 developer** tools.
-4. Click the **network** tab.
-5. Clear the **clear entries on navigate** option, which is selected by default. The icon looks like blue arrow with a red X.
-6. The green play button (**start profiling session**), should be selected by default. This means the capture function is running.
-7. Refresh the the page and reproduce the problem while the capture is running.
-8. Once you have reproduced the issue, click the **export as HAR** icon. The icon looks like a floppy disk.
-9. Click the **console** tab.
-10. Right-click any row and select **copy all.**
-11. Paste the content in a text file and name it **console-log.txt**.
-12. Send both files as shared links in a reply to your case.
-
-### **Edge**
-
-1. In Edge, go to the page within GitBook where you are experiencing trouble.
-2. At the top-right of your browser window, click the Edge menu (⋮)
-3. Select **developer tools**.
-4. Click the **network** tab.
-5. Clear the **clear entries on navigate** option, which is selected by default. The icon looks like blue arrow with a red X.
-6. The green play button (**start profiling session**), should be selected by default. This means the capture function is running.
-7. Refresh the the page and reproduce the problem while the capture is running.
-8. Once you have reproduced the issue, click the **export as HAR** icon. The icon looks like a floppy disk.
-9. Click the **console** tab.
-10. Right-click any row and select **copy all.**
-11. Paste the content in a text file and name it **console-log.txt**.
-12. Send both files as shared links in a reply to your case.
diff --git a/help-and-faq/faq/support.md b/help-and-faq/faq/support.md
deleted file mode 100644
index d550172d..00000000
--- a/help-and-faq/faq/support.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-description: >-
- Our friendly support team is here to help. Learn what information to share and
- when can you expect a response.
----
-
-# How do I contact support?
-
-There are two ways to get in touch with us:
-
-- You can submit a support request via the GitBook app. When you’re logged in, click on the **settings icon** in the [sidebar](https://docs.gitbook.com/getting-started/overview#sidebar). Click **Help & Feedback** and then click **Contact Support**.
-- You can email [support@gitbook.com](mailto:support@gitbook.com) directly.
-
-## What information should I share?
-
-To help _us_ help _you_ as efficiently as possible, please be sure to send us all relevant details:
-
-- If your support request relates to a specific space, please make sure to include a link to it.
-- Please describe the steps that you are taking, what happens when you take those steps, and what you expect to happen instead.
-- If you are running into an error message, please pass along the error message in full.
-- Can you send us a screenshot to show us what you’re seeing? Or, can you send us a short video to show us the steps that you are taking? These are extremely helpful.
-
-## When will I get a response?
-
-We aim to respond to every message within 1 business day. At busy times this might not be possible, but we’ll always get back to you as soon as we are able.
-
-Please note our support team works Monday to Friday, from 9 am to 5 pm GMT (+/- 3 hours).
-
-## Why has the support widget changed?
-
-We’ve made some internal changes to help us improve the support that we offer. As part of these changes, we have moved to a new help desk system. The main differences you’ll notice are:
-
-- We have a new workflow in the GitBook app to use when sending us a support request.
-- Our workflow will gather the key information we need to help us assist you faster.
-
-Please note that **we do not offer real-time support** via this widget, this isn’t something that we can currently provide. We aim to respond as soon as possible and when we do, your inbox will notify you!
diff --git a/help-and-faq/keyboard-shortcuts.md b/help-and-faq/keyboard-shortcuts.md
deleted file mode 100644
index 68679370..00000000
--- a/help-and-faq/keyboard-shortcuts.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-description: Helping you to make changes to your GitBook documentation even faster!
-icon: keyboard
----
-
-# Keyboard shortcuts
-
-Shortcut keys allow easy and quick methods for navigating or editing content.
-
-{% hint style="info" %}
-**Permissions**
-
-All member roles can use keyboard shortcuts.
-{% endhint %}
-
-## Navigation
-
-| Mac | Windows | Description |
-| ----- | -------- | ---------------------------------- |
-| `Esc` | `Esc` | Close a dialog or the search panel |
-| `⌘+K` | `Ctrl+K` | Open the quick find panel |
-
-## Editing
-
-| Mac | Windows | Description |
-| ----------- | -------------- | ------------------------------------------------------------------------------------------------ |
-| `⌘+C` | `Ctrl+C` | Copy |
-| `⌘+V` | `Ctrl+V` | Paste |
-| `⌘+Shift+V` | `Ctrl+Shift+V` | Paste as text, without formatting |
-| `⌘+Z` | `Ctrl+Z` | Undo |
-| `⌘+Shift+Z` | `Ctrl+Shift+Z` | Redo |
-| `⌘+Enter` | `Ctrl+Enter` | Exit from content block (code, tabs, table, quote ...) |
-| `/` | `/` | Open block-insert palette. |
-| `⌘+/` | `Ctrl+/` | Open block-modifier palette. |
-| `⌘+B` | `Ctrl+B` | Toggle bold |
-| `⌘+I` | `Ctrl+I` | Toggle italic |
-| `⌘+Shift+S` | `Ctrl+Shift+S` | Toggle strikethrough |
-| `⌘+E` | `Ctrl+E` | Toggle inline code |
-| `⌘+K` | `Ctrl+K` | Insert or toggle link |
-| `Tab` | `Tab` | 
[GitBook Support](mailto:support@gitbook.com).
+If everything fails, please share the details with 
.png)
.png)
+
+
.png)
.png)
.png)
.png)
button to save.
-
-{% hint style="warning" %}
-Changing a linked space's slug will change the space's canonical URL, and might result in broken links across your site.
-{% endhint %}
-
-To replace a linked space with a different space, click on the **More menu**  in the space's table row and then click **Replace linked space**.
-
-### Reordering linked spaces
-
-Your site displays linked spaces in the order that they appear in your Site structure table. Spaces can be reordered by grabbing the **Drag handle**  and moving it up or down. Alternatively, you can press the **More menu**  in the table row of the space you'd like to edit and choosing **Move up** or **Move down**. The changed order will be reflected on your site immediately.
-
-### Setting default content
-
-If you have multiple sections in your site, one section will be marked as the default. This section is shown when visitors arrive on your site, and is served from your site's root URL. Other sections each have a slug that is appended to the root URL.
-
-If you have multiple variants within a section, one variant will be marked as the default. Like sections, the default variant is shown when visitors arrive on your site (or when they visit a section). Other variants each have a slug that is appended to the section's URL.
-
-To set a space as default, click on the **More menu**  in the space's table row and then click **Set as default**.
-
-{% hint style="info" %}
-Setting a space as default removes its slug field, as it will be served from the section root instead. We will redirect the space's slug to the appropriate path, to ensure visitors keep seeing your content.
-{% endhint %}
-
-### Remove content from a site
-
-To remove the content of a space from a site, click the **Settings** .png)
.svg){kind=link}
.svg){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.png){kind=link}
.svg)
.svg)
.svg)
.png)
-
-When this setting is enabled, the space will automatically inherit any changes made to the customization settings for the parent collection. This is useful if you want to control multiple spaces’ customizations in one place, and removes the need to make the same change multiple times across spaces.
-
-
.svg)
-
-## Setup Guide
-
-{% hint style="info" %}
-A complete example repository for Node.JS is available on GitHub: [https://github.com/GitbookIO/example-visitor-authentication](https://github.com/GitbookIO/example-visitor-authentication)
-{% endhint %}
-
-### Step 1: enable visitor authentication
-
-In your space or collection, open the visibility menu and select **visitor authentication**. (If you're not on an Enterprise plan, you'll be prompted to upgrade.)
-
-
-
-Once enabled, you'll have access to a private signing key for this space. Each space has a unique signing key. You should keep this key secret - make sure not to commit it into your source control repository. We recommend referencing it through a production secrets system in your deployed backend.
-
-
-
-### Step 2: sign a JWT token and grant access to a visitor
-
-Here's an example of creating a JWT token by signing the access data with the private key using the library [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) for Node JS.
-
-```javascript
-const jwt = require('jsonwebtoken');
-
-const gitbookSignKey = '
.svg){kind=link}
.svg){kind=link}
