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.

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.

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:

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:

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.

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

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

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.

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.