The WriteDocs Template is the foundation for creating and deploying documentation portals using the WriteDocs solution. It comes with everything you need to get started quickly.
Welcome to the WriteDocs documentation guide. Follow the instructions below to learn how to create, deploy, and take your documentation to the highest level with WriteDocs.
WriteDocs uses GitHub to integrate your docs with your code, and make source control effortless. Therefore, make sure you have the following requirements checked before getting started:
- GitHub account
- GitHub organization
- Code editor, such as Visual Studio Code.
Start by creating a new repository in your GitHub organization using the WriteDocs Template provided on GitHub. When creating the repository, use the [yourcompanyname]-docs standard to define the repository name. This will give you a structured starting point to build your documentation quickly.
Once your documentation repository is created, follow the steps below to connect the WriteDocs App to this repository. This connection ensures that WriteDocs automatically generates and deploys your documentation.
- Access the WriteDocs App on GitHub.
- Click Install.
- Select Only select repositories and look for the documentation repository created in Step 1.
With these simple steps, WriteDocs will automatically deploy your documentation.
Intially, your documentation will be available at [yourcompanyname].docs.writedocs.io, using the WriteDocs subdomain.
If you are in the Pro plan, you can add a custom domain to your documentation. For additional information, send and email to [email protected] and our team will be happy to help you set up your custom domain.
WriteDocs provides you with a config.json file in your documentation repository where you can quickly customize the appearance and structure of your documentation. You can find more information about setting up this file on the Global Settings page.
When you push changes to the main branch, WriteDocs will automatically update and deploy your documentation.
If you don't have much experience in contributing to GitHub projects or using a doc-as-code approach, you can check our Beginners Guide that covers the basics of working with Git and using a code editor to create docs.
The WriteDocs template includes all the essential components to deploy your documentation portal. Below is an overview of the repository structure and how to use it:
|-- config.json
|-- homepage.html
|-- reference/
|-- media/
|-- docs/
The table below provides instructions on how to use each file and directory available:
| File/Directory | Description |
|---|---|
config.json |
All configurations and customizations of your documentation portal are done through this file. Customize appearance, navbar and sidebar structures, colors, and logos here. |
homepage.html |
WriteDocs uses the content from this file to generate the homepage of your documentation. |
docs/ |
Place all MDX files in this directory to generate your documentation pages. Organize the files according to the desired structure of your documentation sidebar. |
reference/ |
Upload your OpenAPI files here to generate interactive API pages where customers can test your APIs. |
media/ |
Store all images used in your documentation in this directory. You can reference these images when writing your documentation. |
For detailed information on how to use all the features offered by WriteDocs, refer to the WriteDocs documentation.