Build a Markdown-based docs site using DocsifyJS and GitHub Pages
Convert your docs folder into a pretty and modern docs website, built around your Markdown content and a theme.
Using a JavaScript library called "DocsifyJS", this tutorial shows you how by doing some light set up. This can all be done on the GitHub and is simple enough for those without JavaScript experience and does not require using Node.
?> See docsify.js.org homepage or the docsify package on NPM.
Unlike other JavaScript-based frameworks, DocsifyJS needs just a few lines of JavaScript as configuration and the rest of your content is mostly Markdown and YAML. It is built on Vue, but you don't need to know anything about Vue to get the benefits.
This project's site itself is also running on DocsifyJS. 🎉
Start below with the basics, or skip to the later sections with the sidebar to get to menu customization, plugins and styling.
Code snippets and recommendations are provided here as kind of cheatsheet or cookbook, so you don't have to spend a lot of time pouring over all the possible options and features covered in the docs that you probably don't need to know.
?> DocsifyJS is sometimes just called Docsify in this guide. Also known as Docsify.js.
View the source for this tutorial site, which is also built using Docsify:
This project is for you if you answer yes to any of the following:
- Are you new to making a docs site?
- Tired of writing HTML/CSS/JS and just want to write docs using plain Markdown?
- What is DocsifyJS?
- Want to add features and style to your DocsifyJS site?
- Looking for a template which is based on real world use?
- Can I make a build a docs site without having a build step?
This project provides three approaches for choosing a Docsify site to run:
- Use the Quickstart local server
- Clone this repo and start serving the docs repo immediately.
- Set up your own docs site from scratch.
- Convert your docs directory into a docs site hosted on GitHub Pages. Copy from some templates files to get up and running with as little effort as possible.
- Use my DocsifyJS Template repo
- A minimal template which goes with this tutorial.
- Click Use this template to add a copy to you own repos. you'll be able to starting serving a site on GitHub Pages or locally.
Note: The instructions in this repo are intended for Linux and macOS environments.
Some docs site I have built. These give you an idea of content, layout and customization
My requirement was to build a docs site with minimal file/dependency set up and to use existing docs directories, without restructuring or formatting the docs. I found Docsify is ideal for this.
I like that once I have the HTML set up that Incan focus on markdown content and writing a menu using YAML. And there is no build step. Its just a HTML and external JS as static assets. Just deploy to GH Pages or elsewhere.
When you use Docsify with its defaults or very simple tweaks, you get a pretty UI with menus, themes, mobile functionality and a cover page. Page loads are seamless in the app shell, as it is a SPA. These are things that take more effort and code changes or additions, if you want to do them with static-site generators. Docsify also had documentation as its main purpose, unlike some other tools.
There are some downsides like Docsify does not have static site support yet (which makes it weak for SEO rankings) and there are only 4 themes, which are just color scheme changes. And the dark one doesn't have good contrast for certain things.
This great article on dev.to covers a journey from README to Wiki to Jekyll and finally Docsify, if you are interested to compare those.
Docs and Docsify-related links
- DocsifyJS Tutorial repo on GitHub.
- DocsifyJS Template project.
- MkDocs Quickstart project
- As an alternative to Docsify, try this demo / tutorial / template around MkDocs.
- Docsify main repo - docsifyjs/docsify
- Docsify CLI repo - docsifyjs/docsify-cli
This is where the tutorial starts - with an intro to Docsify.
A Docsify site works works without the need to edit your existing docs and without building any HTML pages. The rendering is done on the client-side in a single page application, running on index.html.
Main components of a Docsify site:
- cover page
- Optional.
- Landing page with background color or image and some minimal text.
- homepage
- First page that a user sees, after the cover page. This is a content page written in markdown and it could be the only page of your site if you like.
- index page
- HTML file base of the app.
- This includes JS and CSS calls for setting up and styling the Docsify app. Plus some JS code which you set to customize the app.
- sidebar config
- Optional.
- Describes the menu layout for the left sidebar, using custom ordering and nested structure. Docsify is not aware of directory structure, so this is where you get to define your menu. Alternatively, let Docsify fill the sidebar for you, based on the structure of your homepage (
docs/README.md) file - this works best if you only have a single content Markdown page. If you have multiple pages each with their own auto sidebar, you can us the navbar (top of the screen) to switch between them.
- navbar config
- Optional.
- Describes the menu layout for the top right menu.
Once you have that set up in docs directory and have pushed to GitHub, you can set up GitHub Pages serving the docs directory. Note: Docsify also works with Netlify as per their docs, but this project just considers the GitHub Pages case.
Instructions for creating valid Docsify links in your markdown files.
The Docsify site is served from the docs directory with restrictions on links between files. Therefore you must ensure your markdown files (including the sidebar) are valid.
As usual external resource can be linked e.g. https://example.com.
DocsifyJS will render Markdown links in your docs as appropriate paths in the DocsifyJS structure.
Apply these rules to the target part of markdown URLs [Text](target.md#some-id).
- Links must always be relative to the
docsdirectory and not to the file containing the link.- e.g.
foo.md, which becomes/#/foo. - e.g.
baz/fizz.md, which becomes/#/baz/fizz.
- e.g.
- Links may contain a leading forward slash. This has no effect so can be ignored.
- e.g.
/foo.md, which becomes/#/foo.
- e.g.
- Links may use an ID.
- e.g. To link to heading on the homepage, use
#my-project, which gets converted to/#/?id=my-project. - e.g. To link to another page, use
foo.md#my-project, which becomes/#/foo?idmy-project(note no path extension).
- e.g. To link to heading on the homepage, use
- Do not reference the
docsdirectory in the path. e.g./docs/foo.md - Do not refer to content outside of the
docsdirectory. e.g.../README.md. - If you use relative links between files in the
docsdirectory - make sure to enable this in the app config.
Warning. In the default mode, if you want to link to my-dir/README.md, this will not work as expected.
[My text](my-dir/)It will become equivalent to this.
[My text](/#/my-dir)Which will be a broken URL. Or weird looking e.g. /?id=docsify-cli#/vue-integration/.
If you are linking to a file in a directory like `my-dir
Get around this by using an HTML link.
<a href="my-dir/">My text</a>Or by adding a forward slash - which might break your site like on GitHub Pages subpath sites.
[My text](/my-dir/)If you switch to history Router Mode, this won't matter.
It's best to avoid using HTML tags with hyperlinks and rather use Markdown where possible.
HTML tag hyperlinks will be rendered literally and so will break in the Docsify path structure e.g. href="foo.md" is bad. But [](foo.md) is good.
You can set them up manually, which makes them harder to maintain if your site structure changes. e.g. href="/#/id=my-project" or href="/#/foo.md?id=my-project".
Also note that the root prefix is needed for Docsify paths to work, but you'll also need to hard-code your repo name in which is fragile too. e.g. href="/my-repo/#/id=my-project"
Serve an existing project locally
Follow these steps to set up and run an existing Docsify project locally. In this case, we get a local copy of this DocsifyJS Tutorial project and serve it.
Clone this repo to your machine with one of these commands:
$ # Clone with SSH:
$ git clone git@github.com:MichaelCurrin/docsify-js-tutorial.git
$ # Clone with HTTPS:
$ git clone https://github.com/MichaelCurrin/docsify-js-tutorial.git?> Note: No installation is needed. When the HTML page is opened in the browser, the Docsify library will be fetched from a CDN by the browser.
?> Note When viewing the site, if you scroll down far enough you will see a hamburger menu which lets you dynamically open or close the sidebar. This is always visible on mobile view but not so easy to find, while the sidebar starts out closed on mobile.
Convert your docs directory into a docs site
This tutorial is based on the Docsify Quickstart guide, but rather than giving snippets of file this tutorial lets you copy entire template files to your project, there are TODO items in the templates making it clear what to edit.
Plus, in the template, there are some useful or pretty configurations which have been set after investigating the configurations guide and trying them out on my own project.
Follow to steps in this section copy a base structure and configs from this project to your own, then customize them for your needs.
The repo has an accompanying DocsifyJS Template repo. Follow instructions in that project's root README to copy the base project to your own project's docs. Note this will overwrite any existing files in docs, so make sure you have them backed up or any version control.
Next, view the contents of the docs directory to see what was added.
?> Note that Docsify provides a 404 - Not found page for a bad URL so you do not need to create a 404 page yourself.
?> The minimum you'll need for your docs site is a README.md - either your own or the one copied from above. If you have any other markdown files or folders in your docs directory, leave them there are they will also be used for your site.
To see what the base site look like, start a server now using a command from the serve section. Open the web page URL and keep it open so you can check on it as you make changes in the following sections. If you use the Docsify server, the page will auto refresh on a file save, otherwise you will have to manually refresh.
Edit your homepage (docs/README.md). Complete the TODO items, using the suggestions in this section.
- Anything outside of your docs directory will not be served. Therefore you might want copy the the content from your project root's README.md to the homepage. After that, you could make the root README.md very short, if you don't want to worry about keeping two identical files in sync.
- You might want to opt for short homepage file if you prefer to put more documentation in other docs files.
- Note that you are not required to put in links to other docs file within your homepage file. As that is what the Docsify sidebar. If you do put in any links in your homepage, they must be relative to the docs directory, such as
file.md. See Doc links for more info.
Optionally define a menu for the top right of the page.
See Custom navbar and loadNavbar in the docs.
?> Note: If you enable a cover page and the navbar, the navbar will appear on the cover page. This makes it difficult to navigate as you have to scroll up all the time to get the navbar. Also, if not using a cover page, the navbar will cover the homepage heading but only on a mobile device. Some CSS is needed to fix both of these issues, not covered here. Alternatively, use mergeNavbar: true, if your app config to move the navbar items to the top of the sidebar on a mobile view. This works great.
It's best to include a sidebar. You let it be defined automatically from a file's structure, or you can define a sidebar using an ordered description of pages (which may be nested).
See loadSidebar in the docs.
You may choose to display the sidebar, but have it populated automatically from headings on a single HTML file - the homepage (docs/README.md). This is the way that this project's own docs site is set up.
This solution is great if you are happy to move all your doc content into a single large markdown file, as it means not having to worry about manually updating a navigation bar when you docs change. Especially if you have a many files to manage or they are likely to change in name or structure.
You can also have multiple markdown files in folders, each group with its own sidebar config.
To set up auto sidebar:
- Delete _sidebar.md.
- Open index.html to edit it.
- Set
loadSidebar: falseand save.
!> Warning: If you go for this option without a configured sidebar, do not leave any links in your docs/README.md which refer to other doc files. Although the link may be valid, once you click on the link, the sidebar on that page will reflect the target page rather than the outline of the docs/README.md page, which is inconsistent and jarring behavior.
You can choose to configure a custom sidebar. This is necessary to link to the multiple doc files.
How to set up a sidebar file:
- The format should be bullet points in markdown format.
- Each menu item should be a markdown link e.g.
[Name](link). An item may exist on the menu without a link - this is useful for grouping items together under a menu heading. - The links must be follow restrictions noted above in Linking to pages. If the doc files change (e.g. are renamed or moved), you need to remember to update the sidebar config.
- The bullet points may optionally be nested, using indentation. You may create arbitrary indentation in your sidebar, even if all you files are at the same level in the docs directory.
Example:
?> The sidebar is a markdown file, so you can styling as a **Title**.
- Ensure
loadSidebar: trueis set in the index.html file.- The value of
truemeans*_sidebar.md*will be referenced by the app. - The sidebar is already enabled in the quickstart index.html.
- The value of
- Edit the _sidebar.md file.
- Add items using the guidelines above.
The clickable text above the standard sidebar takes you to the cover page. You can scroll down to the homepage (docs/README.md), but there are no links on the page to the homepage. So add a link to the Homepage with a first entry at the top.
Example of a link to the page page, using root page path and ID of the heading on the homepage.
- [Home](/#my-app)Parts:
- Root path (
/)- The leading forward slash is required here for correct behavior to get to the homepage as root page. As the anchor tag will be invalid on other pages such as
foo.mdwhich has path/#/foo/).
- The leading forward slash is required here for correct behavior to get to the homepage as root page. As the anchor tag will be invalid on other pages such as
- Homepage heading ID (e.g.
#my-app)- This is the ID of the heading on the Homepage (README.md).
- The ID follows the markdown style of headings as slugs (lowercase and hyphens).
- You can also find the ID on page directly if you aren't sure.. Go to the coverpage, scroll down to the homepage and click on the heading. The URL will be something like
http://localhost:3000/#/?id=my-app. The part we want is the end e.g.my-app.
This is really the text of heading element, which has been made lowercase and hyphenated. Copy this to the sidebar file and prefix it with a hash symbol.
?> Note: An alternative would be use the top right nav bar to point to the Homepage, rather than sidebar as here.
Docsify provides a cover page - a simple page that a visitor sees before scrolling down to the homepage which has centered text, a background and a summary of your application.
If you want to use it, make sure coverpage: true is set in your app config.
Then create and edit a docs/_coverpage.md file. You can also use the template project's cover page on GitHub as a reference.
You can add additional buttons to the bottom of the homepage, but there should be no gaps between the lines in your file. And the last one will be solid while the others will be transparent.
You can delete the cover page and disable it in index.html.
You can change the background image for your cover page.
If you do not set a cover background, you'll just get a random one on every page load - it might be a solid color or a gradient.
The Docsify site explains how to set a background image or color here.
Your background image code should come at the end of your coverpage file. As Docsify looks for an image there then uses CSS to place the image behind the content and give it a faded grey look.
See code examples below for adding a custom background image:
- Solid color. The text label must be the word
color.
- Gradient color.
- Choosing a custom gradient was supported but does not work anymore, so it is not covered here.
- Image. The text label can be anything - use some fallback text in case the image is broken.
You probably want to set the themeColor in the index.html to go well with your coverpage. See Theme color below.
e.g. This tutorial has a grey value for cover and blue value for theme color.
You could include an image (logo, photo) above your project title. For example, you could do this if you have a file in a docs/_media directory.
<!-- background image -->
Edit index.html.
Not covered here - see jhildenbiddle/docsify-themeable for more control on custom styling and theming.
Optionally set a theme color. This affects how some content looks, such as quoted blocks, underlined text and buttons. This will default to theme's default if not set manually. i.e. green for Vue and blue for Buble.
window.$docsify = {
themeColor: '#3F51B5',
};More on Docsify theme color.
Find the style which is set in the <head> tag, which looks like this.
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/<THEME>">Replace the end of URL with one of these four themes. They have the same layout but different colors.
vue.cssbuble.cssdark.csspure.css
?> You can optionally remove /lib from the theme URL to get the uncompressed CSS file.
Read more on the Docsify themes guide.
Note: The Buble theme has sidebar headings which are not distinguished from the sub items. Therefore you can add this to index.html to get bold headings similar. Based on vue.css.
<style>
.sidebar .sidebar-nav>ul>li {
font-weight: 700;
margin: 0;
}
</style>You can easily reuse the theme color set early:
.myButton {
background-color: var(--theme-color);
}Here is a some useful button styling I added to a site. The Bess CSS Button Generator site was useful for discovering some attributes.
.myButton {
background-color: var(--theme-color);
color: white;
/* Slightly larger */
font-size: 1.0em;
/* Round the edges */
border-radius: 8px;
padding: 6px 12px;
/* Change cursor on hover */
cursor: pointer;
}
.myButton:hover {
filter: brightness(110%)
}
/* Shift the button down on click */
.myButton:active {
position:relative;
top: 2px;
}The configuration steps above already get you a prettier and more usable site in my opinion than the barebones one which the Docsify init command or their Quickstart guide gives you. This section covers advanced steps - you may skip these and jump straight to the GitHub Pages section.
You can update the config parameters passed in on the index.html page. There are some useful things there in like adjusting the sidebar levels, putting a logo in the sidebar or setting your root README.md as your homepage. There is even a search bar you can add.
Links
- For available parameters, these are documented on the Docsify Configuration page.
- For defaults, see the Docsify repo's src/core/config.js script.
- To see an app config in use, see index.html of DocsifyJS Template project.
Sidebar
Config options relating to the sidebar. Default values are shown here.
window.$docsify = {
// Recommended to set this to true - when transitioning between pages,
// it can look weird if you don't get to the top of the page.
auto2top: false
// Maximum sidebar depth.
maxLevel: 6,
// How many sub levels to show in the sidebar.
// This is useful for precision for a custom sidebar, but you can leave this out.
// Try a value of 2 to add subheadings. This is particularly useful if you have
// a lot of headings on a page.
subMaxLevel: 0,
// Add your logo to the top of our sidebar menu.
logo: '/_media/icon.svg',
// Name which appears at the top of the sidebar.
name: 'docsify'
};Homepage
Configure the homepage settings. You might not need this, but in case you want to use a different homepage target. These recommendations come from the docs.
window.$docsify = {
// Change to /home.md rather than /README.md file.
homepage: 'home.md',
// Specify the README.md at the root of your repo, rather than in the docs directory.
homepage: 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md'
};You can use a custom favicon, if you added one.
Add this to the head tag in index.html.
<link rel="icon" href="_media/favicon.ico">To run your own script tags, you must enable it with a parameter.
- `index.html
window.$docsify = { executeScript: true, }
page.md<script> console.log('My script'); </script>
Note that Vue is enabled by default.
See executeScript in the docs for more info.
If you want to run an external script, using the External script plugin.
index.html<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>
page.md<script src="main.js"></script>
Note that this does not support embedding gists, even if use executeScript. There is a JS error on running document.write on an asynchronously loaded script.
Optionally add plugins to extend your site. This is typically done by adding a JS link at the bottom of your index.html page.
Here is a narrowed down list of plugins of interest:
| Plugin | Description |
|---|---|
| External script | You need thus plugin if you want to place a script tag on the page that loads a .js script. |
| Google Analytics | Configure the app with your GA ID to add tracking. |
| Tabs | A Docsify.js plugin for displaying tabbed content from markdown. |
Also of interest:
- For pulling in JSON data and not just markdown files:
- The DocsifyJS site covers long lists of plugins and how to use them:
Load and configure this plugin to add the Edit on GitHub link in the top right of each page (excluding the cover page).
- njleonzhang/docsify-edit-on-github on GitHub.
Load this plugin inside the head tag.
<script src="//unpkg.com/docsify-edit-on-github/index.js"></script>Then your configuration set up in the body tag will using a vlue set by the script.
Configure the plugin in the body. See below.
Basic usage
Function call:
EditOnGitHubPlugin.create(docBase)Here we just use one argument and ignore rest.
Arguments:
docBase- Required.
- It should be a full URL to the document folder of your GitHub project.
- Here is the general form - use your own repo details and typically
BRANCHismasterandDIRECTORYisdocs.https://github.com/USERNAME/REPONAME/blob/BRANCH/DIRECTORY/ - Example based on this repo:
const docBase = 'https://github.com/MichaelCurrin/docsify-js-tutorial/blob/master/docs/'; EditOnGitHubPlugin.create(docBase);
Full example:
const repo = 'https://github.com/MichaelCurrin/docsify-js-tutorial';
window.$docsify = {
name: 'DocsifyJS Tutorial',
repo: repo,
plugins: [
EditOnGitHubPlugin.create(
repo + '/blob/master/docs/'
)
],
};?> Note that repo is defined first and then used in two places. This makes the code easy to maintain as it avoids duplication.
?> Note that plugins are generally not defined on app config inside the plugins field, but it applies here at least. Docsify handles it here.
Then save and view the site.
Advanced usage
Function call:
EditOnGitHubPlugin.create(docBase, docEditBase, title)Arguments:
docBase- As in above section.
docEditBase- Optional - defaults to the first argument if not set.
title- Optional - defaults to
'Edit on github(unfortunately lowercase). - Set to override the message. e.g.
'Improve this page'or'Edit on GitHub'or'📝 Edit this page'. - Example:
EditOnGitHubPlugin.create( repo, null, 'Improve this page' );
- Optional - defaults to
See Router mode in the docs.
The default is hash.
window.$docsify = {
routerMode: 'hash'
};This gives URLs like:
/#/about
The advantage is that navigating between pages does not trigger an entire refresh of the page (and a white screen for a bit)
But, if you want slash URLs without the reload, you can configure Docsify to do this.
This relies on the the browser's HTML5 History API, so won't work in older browsers.
window.$docsify = {
routerMode: 'history'
};Then your paths will be like:
/about
The JS will push state to the browser to control navigation, avoiding a reload.
?> This can make things weird with the Docsify dev server when saving a file and refreshing but this should be okay on a deployed site.
The caveat is that any bad URLs will not fallback to the app, going server error page. And clicking on an external URL to get to your site will also break.
So you need to accept that and check your links carefully or you need to configure a page routing on Nginx or Netlify for example, to handle your routing properly (see Vue Router docs). GitHub Pages unfortunately does not let you configure that.
When it comes to converting your site to a static site for SEO benefit, this is something that is worth setting.
If you followed the steps above, you'll have a locally running docs site.
Now, commit and push the files to GitHub.
Next, edit your repo's setting on GitHub. Select the option to serve the docs directory of the master branch as GitHub Pages site. When you refresh the settings page, then you will see a link to your site there.
Open the link in the browser.
To make the most of Docsify, update your content using the next section.
How to update and add to the content of your doc files so that they work well in Docsify
You can embed content such as
- Media - video, audio, iframes (
.html) - Code that appears as a code block
- Markdown or HTML that gets rendered on the page seamlessly.
Add the ":include" parameter in a markdown URL reference. Here is the format:
[LABEL](PATH ":include")If you want to embed as a code block, you can use the automatic formatting. But markdown and HTML files need to be marked as a code using type parameter if you want them as code rather than HTML.
":include :type=code"
The path could be:
-
On the static server. e.g.
foo/hello.md[hello.js](/path/to/hello.md ":include")
-
URL for a file on a public GitHub repo.
- e.g.
[hello.md](//raw.githubusercontent.com/UserName/repo-name/main/hello.md ":include") [\_sidebar.md](//raw.githubusercontent.com/MichaelCurrin/docsify-js-tutorial/master/nested-example/_sidebar.md ":include :type=code")
- Make sure to use the raw URL so you only reference plain text andbnot the entire GitHub UI HTML.
- A protocol of
//is recommended, sincehttps://is needed for a remote andhttp://for localhost, to avoid a CORS error.
- e.g.
-
A gist reference.
- See instructions in this guide.
See the Docsify Embed Files help for forcing types and using fragments.
Render a code snippet - formatted automatically.
Code:
[example.js](_media/example.js ':include' )Result:
If you have a site on GitHub Pages subpath, make sure to avoid leading forward slash.
Render markdown as code snippet. Use the type parameter.
Code:
[\_sidebar.md](_coverpage.md ':include :type=code')Result:
Render target Markdown file as HTML. Leave out the type parameter.
Code:
[example.md](https://docsify.js.org/_media/example.md ":include")Result:
Raw Markdown at that URL:
!> Do not put the URL in a bullet point as it will become an ordinary link.
!> Do not put two embed items in a sequence without some characters in between, otherwise you will get a JS error rending the page. Putting an empty line between them is not sufficient.
!> If you embed a URL of a GitHub file, remember to use the Raw URL otherwise you will get an error.
To break up your doc content and highlight paragraphs, you can now use styling that comes with DocsifyJS.
Here are examples. Note that these will look weird when viewed directly as markdown but DocsifyJS will render them.
Code:
?> Info content.Result:
?> Info content.
Code:
!> Warning content.Result:
!> Warning content.
Docsify is built on Vue.js. So the community has provided a section of the docs for adding Vue to a Docsify page.
I followed that guide to put together a Vue demo and basic Vue-Docsify integration intro.
You still have to add Vue to your external JS assets, but at least the app is initialized for you, which saves some code.
Go to Vue Example on this site.
That sample has its own files like _sidebar.yml and index.html, so it is a demo site hosted within this main tutorial site.
Summary of using Docsify's command-line tool
See resources:
- Docsify Quickstart on Docsify homepage.
- Docsify CLI project's docs.
Follow the instructions in Quickstart local server.
Creates new docs
Set up an initial README.md (duplicated from project root), index.html and .nojekyll in your a target directory. If you don't want the CLI to do it for you, you can create the files by hand or use this project's quickstart directory to get you going.
e.g.
$ docsify init docsRun local server to preview site.
Serve the target directory as a docs site locally. This includes hot reload, to refresh the page on file changes. See serve options above.
e.g.
$ docsify serve docsServing .../docsify-js-tutorial/docs now.
Listening at http://localhost:3000
Serves at localhost:3000/, or a different port if there is already a Docsify server running.
This uses is the main use for Docsify - an index.html page is served, the JS is loaded on the frontend and then markdown pages are requested and converted to HTML as needed. It is a Single-Page Application, so will work great from a user perspective but will score low on search engines. Even though the SEO crawlers can handle JavaScript, there is limited "crawl budget" for a JavaScript-based SPA so this means less of your site is crawled or your site is rated poorly. Constrast with the option below.
Server for SSR
This command is for Server-Side Rendering.
e.g.
$ docsify start docs[SSR] Serving docs now.
Listening at http://localhost:4000
Serves at localhost:3000/
This runs a Node.js server which pre-renders then serves HTML to the browser. This should make almost no difference to the end-user.
This approach is ideal for scoring higher on search engines, as the pre-rendered HTML is easy for a crawler to read and it does not use up the "crawl budget".
This command is easy to run locally.
Unfortunately this solution does not work on static site solutions like GitHub Pages or Netlify. The Docsify docs recommend using the now command to publish a Node.js app for free to vercel.com/ (previously zeit.co).
Although SEO crawlers can do better at sites like single page application, Docsify is still said to not be SEO-friendly, compared with static sites where all HTML is pre-rendered. Even though crawlers are getting better at handling JS for SPAs, I've read that this eats up the crawl budget so the crawler doesn't get far in your site.
However, Docsify provides the option of pre-rendering all the views as static HTML. This can improve SEO.
See Server-Side Rendering section of the Docsify docs.
I don't think it'll includes a sitemap file.
Docsify is a Single-Page Application library. It is not a static-site generator (though, hopefully this will change when Docsify version 5 comes out).
If you are into Rust, check out mdBook to generate an online book from Markdown. It works great as a docs site generator.
Jekyll and Hugo are excellent options for static site generators, not just for docs sites. They can use themes suited to documentation and they can build off of a docs directory. See more info in my Jekyll Resources.
If you are interested in a Jekyll template that is built around presenting a docs site specifcally, see jekyll-gh-actions-quickstart.
These are just tools to build a site. What is appropriate depends on your use-case, how much you need to customized the site and how much effort you want to spend on installing/running/maintaining the project.
I find Docsify light to add to a project and to use for new projects. So it is a great fit for me.
A static site generator can be heavy to set up and manage.
There are dependencies to manage - they might have to be upgraded if their are security vulnerabilities or they are no longer available. Such as plugins and themes for Jekyll. And plugins for Hugo. Plus you probably need a couple of JavaScript or CSS files that either you or a theme added. Such as Query. This Docsify project only needs exactly one JavaScript and one CSS file.
There is HTML to build locally and on the remote. While Docsify needs no dependencies to serve a site, Jekyll sites needs jekyll installed and Hugo sites need hugo available.
A static site needs to be customized in depth or needs a theme set up which also takes effort. You may lose or gain functionality when switching between Jekyll themes because they use their own templates and layouts. MkDocs is another light alternative but have to install some themes and plugins locally.
You probably have to add front matter to your doc files so they can inherit from layouts and have the correct metadata like title.
As with Docsify, you will probably have to create a config file which covers the structure of your project for use in the sidebar.
Unlike building static files with HTML, with with Docsify there is a single page application running off of a index.html - on each request, a markdown file is fetched by the client and rendered as HTML with a theme and menu. The performance will depend more on the server when serving static HTML pages (prebuild and serve page on the client) or on the client when using a single page application (build structure on the client).
Also, the Docsify approach will only work if JavaScript is enabled.
The Docsify site says it supports back to Internet Explorer 11, so that at least helps for a wider audience of users.