Docusaurus is an open-source static site generator developed by Facebook. It is mainly used for building technical documentation and API references. However, Docusaurus is not a dedicated API documentation tool, and there are some challenges associated with it. In this article, we'll introduce you to an easy way to migrate your Markdown files or built web pages from Docusaurus to Apidog.
Come try out Apidog's simple yet intuitive user interface by clicking the button below!
About Docusaurus
Docusaurus is an open-source static site generator developed by Facebook. It is mainly used for building technical documentation and API references. Docusaurus is fully compatible with the Markdown format, allowing you to automatically convert Markdown-written documents into web pages.
Challenges in Creating API Documentation
While Docusaurus is generally suitable for creating API documentation, it is not a dedicated API documentation tool, and there are some challenges:
- Lack of API reference specialization
As a general-purpose technical documentation tool, Docusaurus may lack specific features for API references (such as parameter definitions, highlighting of request/response examples, etc.). - No integration with API specs
Docusaurus does not have the ability to automatically generate documentation based on API specs, so you need to write everything manually. It cannot integrate with spec-driven development like OpenAPI. - Version management challenges
If API resource paths or parameters change with a version update, it may be difficult to track with Docusaurus alone. - Immature plugin ecosystem
There are not yet enough plugins dedicated to API documentation, which can make customization challenging.
As a result, Docusaurus may be too general compared to tools dedicated to creating API documentation. For those looking for an alternative to Docusaurus, we recommend Apidog, a tool that is fully compatible with the Markdown format while also supporting the generation of intuitive and clean API documentation from API specs. Apidog is the most suitable option for those who want to create API references.
Migrating Docusaurus Files to Apidog
In this article, we'll introduce you to a solution for migrating your Docusaurus files to Apidog to build a more comprehensive API reference.
Apidog supports various Markdown syntaxes and can automatically convert Markdown files into web pages, just like Docusaurus. Additionally, Apidog can generate clean API documentation from API spec files, allowing you to list Markdown web pages and API documentation pages together.
button
Migrating from Docusaurus to Apidog can be highly beneficial, as it allows for more appropriate creation and management of API documentation.
Migration Requirements
To migrate your Docusaurus files to Apidog, you'll need the following:
- An Apidog account: If you don't have one, sign up for Apidog now.
- The original Markdown files for your website: These are typically stored in the
docs/orblog/folders of your project.
1. Create an HTTP Project in Apidog
Create an HTTP project in Apidog.
2. Migrate Docusaurus Markdown Files to Apidog
After creating the HTTP project, go to the left menu, select "Settings" → "Import Data," and choose "Markdown." Here, you can import your Docusaurus Markdown files.
- When importing Markdown files to Apidog, you can define the filenames yourself. You can either import the Markdown files without changing the filenames or set the first line of the file content as the filename.
3. Edit Markdown Files
After successfully importing your Markdown files, you can easily edit them in Apidog.
- Unlike Docusaurus, Apidog also supports creating API documentation. You can easily generate documentation pages from API spec files and list API documents alongside your Markdown files.
4. Publish the Project
Once you've finished editing, you can publish your project. Go to the left menu, select "Share" → "Publishing Settings" to publish your project.
- Using a Custom Domain: With Apidog, you can deploy your project to your own domain. Click the "Edit" button for "Custom Domain," verify your ownership of the domain, and you'll be able to deploy this project to the specified domain.
5. Verify the Migrated Project
After publishing your project on Apidog, you can access it via the domain you specified to view the project page. All your Markdown files will be automatically converted into web pages, and your API specs will be automatically converted into documentation pages.
Summary
In this article, we explained in detail the steps to migrate files from Docusaurus to Apidog.
While Docusaurus is suitable for creating API documentation, it has some challenges. On the other hand, Apidog fully supports Markdown and offers features tailored for API documentation creation, such as automatic documentation generation from API specifications. Apidog allows you to directly import Markdown files from Docusaurus, making it a tool that enables smooth creation and management of API references. We recommend referring to the steps outlined in this article to migrate your Docusaurus assets to Apidog.
By migrating to Apidog, you can expect the following benefits:
- Centralized management of Markdown and API documentation
- Improved efficiency through API specification-driven approach
- Robust version control and customization features
- Ability to publish to custom domains
- Achieving both quality improvement and maintainability of API documentation
Apidog is a powerful option when you aim to balance the quality and maintainability of your API documentation. We hope this article will assist you in the migration process.
