How to create great documentation with Docsify

Documentation is essential to the success of your product. Without documentation, it becomes more difficult for people to use your product. And documentation is equally important if you’re running an open source project.

Creating a documentation site can be difficult, especially if you’re new to front-end development.

I’ve been working as a front-end developer for the past 8 years. During that time, I have created documentation using many frameworks such as Next.js, nextra, content layer, Ghost CMS, lume (deno), docusaurus, and Mark doc.

However, using many of them requires significant knowledge of JavaScript, Next.js, and React. You may encounter challenges such as:

1. Lack of knowledge about JavaScript, React, or other necessary tools
2. Document versioning
3. composition
4. introduction

This guide introduces powerful tools to help you create documents without requiring much technical knowledge.

What is Docsify?

We recommend the following tools to resolve this issue: document. Docsify is a simple and lightweight documentation generator. You don’t need to know JavaScript or React to get started.

Docsify comes with no configuration, no statically built HTML files, support for multiple themes, a built-in plugin API, and full-text search support through plugins. It also deploys to a wide range of platforms including GitHub Pages, GitLab Pages, Firebase Netlify, and Vercel.

I’ve created a demo project to show you how to use it. Source code is available on GitHub. Also check out our live demo site.

How to set up and use Docsify

You can create a new project using docsify-cli. To use docsify-cli, you need to install Node and NPM if you don’t already have them installed.

npm install -g docsify-cli
# or
yarn add -g docsify-cli
# or
pnpm add -g docsify-cli

The command output should look like this:

❯ pnpm add -g docsify-cli

Packages: +198
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 199, reused 114, downloaded 84, added 198, done
.pnpm/docsify@4.13.1/node_modules/docsify: Running postinstall script, done in 196ms

/home/rajdeepsingh/.local/share/pnpm/global/5:
+ docsify-cli 4.4.4
+ pnpm 8.7.0

Done in 13.9s

Create a new project using docsify-cli init options.

➜ docsify init docs

Initialization succeeded! Please run docsify serve ./docs

You can also specify --theme and --plugins.

➜ docsify init docs --theme buble --plugins

For more information about docsify-cli, see the documentation page.

Next, start your local development server using docsify-cli. To do so, run the following command:

docsify serve docs
# or
docsify serve .

The local server runs on the local 3000 port.

When you open the website in your browser, it should look like this:

Docsify folder structure

Docsify has a simple folder structure. By default, when you create a new project with docsify-cli, there are three main files:

├── index.html // This is an HTML entry file.
├── .nojekyll  // This is helpful when you deploy your project on GitHub pages.
└── README.md  // This is the home page or / router

How to customize Docsify

Docsify comes with many customization options and requires no additional knowledge to configure. It’s as easy as copying and pasting the code.

This guide describes some of the most common customization options. See the Docsify documentation for pre-configuration.

1. Basic configuration
2. loading screen
3. Side bar
4. header
5. cover page
6. Plugin
7. theme
8. introduction

Basic configuration

In the basic configuration, you can change or add a logo, name, GitHub repository link, theme colors, and more.

The code to do this is: You can enter your own details.

 <!-- index.html -->
 <script>
      window.$docsify = 
        logo: '/_media/icon.svg',  <!-- add logo -->
        name: "Document",  <!-- Website name it appears in sidebar. -->
        nameLink: '/',  <!-- url for name -->
        repo: "officialrajdeepsingh/docsifyjs",<!--github repository-->
        maxLevel: 2,  <!-- Maximum Table of content level. -->
        themeColor: '#3F51B5', <!-- Customize theme color -->
      ;
</script>

loading screen

Enabling loading screens and dialogs is usually very difficult, especially when using JavaScript or the React.js ecosystem.

Docsify allows you to enable loading screens out of the box. Simply write text along with HTML elements within your app ID and it will appear as a loading screen. It will be as follows.

<!-- index.html -->
<div id="app">Please wait...</div>

<!-- or -->

<div id="app">
<h1> Please wait... </h1>
</div>

By default, the table of contents is displayed in the sidebar. But it’s very easy to customize. First, you need to enable the sidebar.

<!-- index.html -->
<script>
   window.$docsify = 
       
        loadSidebar: true, <!-- Enable sidebar -->
  
   ;
</script>

Then create a new one _sidebar.md Open the file at the root level and paste the following code.

Your sidebar should now look like this:

By default, you won’t be able to see the Navbar on your Docsify site:

But don’t worry. It can be changed. To display the Navbar, you must first enable it:

<!-- index.html -->
    <script>
      window.$docsify = 
       
        
        loadNavbar: true,     <!-- enable navbar -->
       
      ;
    </script>
  </body>
</html>

Then create a new one _navbar.md Open the file at the root level and paste the following code.

* Getting started

  * [Quick start](quickstart.md)
  * [Writing more pages](more-pages.md)
  * [Custom navbar](custom-navbar.md)
  * [Cover page](cover.md)

* Configuration
  * [Configuration](configuration.md)
  * [Themes](themes.md)
  * [Using plugins](plugins.md)
  * [Markdown configuration](markdown.md)
  * [Language highlight](language-highlight.md)

The Navbar looks like this:

cover page

First, enable the cover page in docsify using the following code:

<!-- index.html -->
<script>
      window.$docsify = 
       
        coverpage: true,     <!-- enable coverpage -->
        
      ;
</script>

The next step is to create a new one _coverpage.md File.

# Learn Docsify 
### Learn the docsify start from beginner.

[Start Learn]()
[Github](#/README)

The website cover looks like this:

Covers and UI are theme-dependent and will vary from theme to theme.

Plugin

Plugins provide additional features and functionality to Dicsify and help improve the user experience.

You can create and use plugins according to your own requirements. Dtransform There are many plugins available that are open source and created by various contributors.

You can use any plugin by simply copying and pasting the code. You can also create your own plugins using docsify.

How to use third-party plugins

This example uses the docsify plugin to functionally enable the search bar.

To enable the search bar, copy the following script and run index.html File:

<script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

The search bar should now be visible and functional on your site. The search plugin also allows you to configure various features. For more information, see the search plugin installation and configuration page.

How to create your own plugins using docsify

To create your own plugins with docsify, there are built-in hooks that you must use in your plugins.

Docsify has six built-in hooks. init, mounted, beforeEach, afterEach, doneEachand ready.

1. init: Called once when the docsify script is initialized.
2. mounted: Called once when the docsify instance is mounted in the DOM.
3. beforeEach: Called every time the page loads before the new markdown is converted to HTML.
4. afterEach: Called every time the page loads after the markdown has been converted to HTML.
5. doneEach: Called every time the page loads after new HTML has been added to the DOM.
6. ready: Called once after the first page is rendered.

You can use these hooks to create plugins. For more information on creating your own plugins, please visit our custom plugins documentation page.

This example uses the beforeEach plugin hook to create an edit button.on every page[ドキュメントの編集]A button will appear.

<!-- index.html -->
    <script>
      window.$docsify = 
        
        plugins: [
        
        <!-- write own custom plugin -->
        function editButton(hook, vm) 

          // call the hook
          hook.beforeEach(function (html) 
           
            var url = " + vm.route.file;
            
              // basic route fix 
            let tempFile = url.replace("docsifyjs/README.md", "README.md",)
              ? url.replace("docsifyjs/README.md", "README.md")
              : url;

            // Add Edit Button
            var editHtml = "[📝 EDIT DOCUMENT](" + url + ")n";

            // Add edit button on top of file
            return editHtml + html + "n----n" + "Last modified " + editHtml;
          );
        ,
        ],
        
        
      ;
    </script>

theme

Docsify has both official and community-created themes. You can use any of them. Another advantage is that you don’t have to write any additional code when switching themes.

<!--vue theme -->
<link rel="stylesheet" href=" />

<!-- buble theme -->
<link rel="stylesheet" href=" />

<!-- dark theme -->
<link rel="stylesheet" href=" />

<!-- pure theme -->
<link rel="stylesheet" href=" />

You can choose whether to compress theme CSS files. Compressed CSS files are minified versions of themes and are lightweight production-ready CSS files. On the other hand, uncompressed theme CSS files are useful for development.

Simply copy the CSS theme (Vue, Bubble, Dark, Pure) file and paste it inside the head element. The theme will also change accordingly.

As for unofficial themes, I think the docsify-themeable theme is the best option.

introduction

Docsify has various options for deployment. Docsify sites can be deployed to GitHub Pages, GitLab Pages, Firebase Hosting, VPS (Nginx), Netlify, Vercel, AWS Amplify, and Docker.

Some platforms, such as GitHub Pages, use a GitHub repository to directly deploy your docsify site without creating any configuration.

Here’s the process for that:

you go to setting > page > sauce > Then select Deploy from branch. > branch > Select the branch with the folder and click the Save button.

This may take some time depending on the size of your website. Once the deployment is complete, you should see your production URL.

conclusion

Docsify is a powerful tool for generating documentation sites. With docsify, you can focus on document creation, not UI design.

Docsify is a good option for developers who are not very familiar with JavaScript. If you’re focused on low-level languages ​​like C++ or Rust, docsify lets you start writing documentation with one command.

I recently used docsify for the awesome-nextjs repository. Easily deploy to GitHub pages without any configuration.

Please note that there are two Disadvantage To document:

1. Docsify does not generate dynamic SEO meta tags for your pages. Only the title and description are generated.
2. docsify themes do not provide a modern UI feel.

But still very useful! Enjoy creating your documentation 🙂