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 w rite 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 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 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 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 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 https //docs archbee com/hosting spaces on a custom domain 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 https //docs archbee io/authentication options? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 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 & dev 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 personal 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 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 https //docs archbee com/space links and start building your navigation 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 https //docs archbee io/custom landing page? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 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 https //docs archbee io/custom css? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 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