Create a docs website

Documentation comes in many shapes and forms. You might already have some resources or need to start from scratch. Let's cover how to add content with Archbee.

a) write in Archbee

Once you create a new document, you can start adding content using either markdown shortcuts or any of the 30+ custom blocks.

The custom blocks help you format the content as you need. To open them, type forward slash - / - in the editor and go through the options.

The blocks are grouped under Basic, Media, Developer, Embed, and Content Reuse.

For example, if you want to dynamically link to other documents, type @ and the document title. This will connect to the document id. If you change the title or the position of the document, the link will always point to it.

Another example is calling out the block name. Hit / and type the block's name, e.g., /verticalsplit, which will filter out the block you want to use.

The third option is to use parentheses, and the name of the block - e.g. (api) - will add the API endpoint block.

b) copy-paste

The old-school copy-paste brothers. But why cover this one? Since Archbee's editor supports Markdown, if you want to paste in this format, you might get the following message:

We have detected some Markdown content in your clipboard. Are you trying to paste Markdown?

If you click the cancel button, the content will not be rendered, and if you click OK in the dialog box, we will convert the Markdown to Archbee's blocks.

So you have a code example that will be rendered as a code editor block in Archbee.

c) import Markdown or Word files

Copy-pasting works just fine, but if you have Markdown or Word files, why not import them into a Space?

Before importing any content, make sure you click on the Space where you want to import the files. You just clicked on the type of file you have and saved minutes of copy-pasting from other sources.

d) import OpenAPI/Swagger files or Postman collections

When it comes to documenting APIs, you have multiple options.

Let's say you are using the OpenAPI (previously Swagger) standard. This allows for easy import and sync of the files.

Once imported to Archbee, the content will be rendered in a 3-column layout that allows for easy-to-manage documentation.

e) sync a GitHub repo

It happens that the documentation is written in a GitHub repository, and you can continue writing in GitHub and sync the repo with an Archbee Space. The benefit is that you can publish that Space to your custom domain and add other Spaces with additional information like API references.

Set up the custom domain and access control

Before you get started with the content, take a small step that will make a difference later. Set up your subdomain to have access to the preview and production environments. Go to the documentation page and follow the steps to add your custom domain.



Multiple options are available under the General tab - you can switch off the Indexable by search engines (if public) from the same Space Settings. You often want this activated so that users find your site on the search engine results page. You can go to the Public access control option and pick any of the fice options for more control.



• None: does exactly what the name says, keeps your settings regarding the public Space.
• Password: Set a Space password. Everyone with the link and password will be able to read the content.
• Guest Accounts: Create guest accounts. Everyone with the link and a guest account can read the content. Guest accounts are not charged as seats in Archbee.
• Magic link: You enter specific emails or allowlist entire domain names, and users will authenticate using a link that we send to their email address;
• JWT authentication: Check the **doc page **for how to set it up. It's a perfect option if you don't want the users to log in each time.

Start building pages

Before you write any documentation, consider the main topics you will cover. This time a pen and paper might help you to draw the structure.

Next, create a document, convert it to a category, and give it a name.

Once you have these, you are ready to add documents under each category.

Start with a document introducing the main things a user will find on the documentation site. It doesn't have to be complicated; here is how we did it in our User Guide:

• Getting Started
• Editor
• Documents
• Spaces
• Hosted Spaces
• Organizations
• Import & Export
• Integrations
• Guides
• Public API
• Misc

When you start to add content, it's essential to have a workflow. Here's a potential one, but you might want to adapt it:

• Start the draft in My Private docs. This will help you write anything that you don't want to share with the team yet.
• When ready, move it to the public Space
• Ping a teammate that the doc is ready and needs to review it
• If any, add inline comments where input from other users is required.
• After you are comfortable with the changes, publish to preview to see the staging site.
• If everything looks good, hit publish to production and announce that everything is live.

Working with templates makes it easy for contributors to start writing content. You can save a set of templates to help you kickstart content production. If you need inspiration, when you create a new document, you will see a button called: Start with a template at the bottom of the page. To build your own templates, go to the navigation on the left side, Templates, and start creating docs with the structure your documents need.

You might as well introduce the custom blocks that an author will be using or add examples from other sources.

Permalinks and SEO settings

These options are at the document level. So you need to click on the three dots on the top right side and pick SEO Meta Controls.

Add a relevant title, change the URL, write a meta description or upload an image for previews.



Brand and customize your docs website

In the Appearance tab, you will find the banding options like Accent Color, Logo, and Favicon, along with other options for the template.



Archbee Appearance Options

Create a navigation menu with multiproduct or product versions

Depending on the type of products or services, you might want to have different Space URL paths.

You can have a Space as the primary docs and create different Spaces for other products or even versions of them.

There's a shortcut! You can create a clone of any Space if the changes are incremental. This will help you keep the structure and make the edits for the new version.

So if versioning and multiproduct is something you need, use a different Spaces and append it with the relevant path or custom domain.

Go to Space links and start building your navigation.



Archbee Space Links

Craft a landing page

The main goal of the homepage is to help the visitor go to the next page.

Building a landing page for your documentation website doesn't have to check the same practices for a presentation website.

The first document page is important to introduce your product or service to the users, so keeping it short and setting expectations goes a long way.



You can use the Custom landing page feature and add your HTML for more control over the first page. There are many options to get inspiration from, and if you want to change the look and feel of the first page, this is your option.

Here is how one of our customers built their starting page for their help page.



Add custom code

Use Custom CSS if you want to add your own flavor to the documentation site. If you are familiar with CSS classes, you will find some starting ab- and you can target them.