Render a markdown site with Docsify

Dec 10, 2024 4 min read Tools

(Photo by Lance Anderson on Unsplash)

So you’ve got a collection of markdown files. Maybe its a personal knowledge base, or a team wiki, or project documentation, or even a statically-generated website like tygertec.

There’s a lot to love about markdown :

Easy to edit
Easy to learn
Fairly easy to read
Plain text format will be readable forever
Easy to throw in a Git repo for change tracking

In fact, I’m writing this blog post in markdown.

Most of the time, searching, viewing, and editing markdown files is as easy as some combination of:

git grep
git ls-files
bat <filename>
vim <filename>

For the IDE inclined, you can easily open the whole directory in something like VS Code (code . from the directory containing the markdown). VS Code can even preview markdown files as pretty HTML. However, slumming around your markdown in VS is a little clunky. What if you want a more streamlined way to view ALL your markdown files rendered as a website?

Well, there’s Hugo, which I ❤️ love . It’s a fantastic production-ready static site generator, and would work just fine. However, it does expect your markdown files to be in a certain format. We’re looking for something quicker, a little dirtier, but still beautiful.

How about Docsify?

Docsify is a “magical documentation site generator” that uses Javascript to render a website on the fly from your markdown files.

All you do is install the Docsify CLI, initialize it in your markdown directory, and then serve the files using its built in web server. As a bonus, you can add plugins to search your files, support Mermaid markdown diagrams, and more.

It’s as easy as 1-2-3:

Install the Docsify CLI: npm install -g docsify-cli
From your markdown directory, initialize Docsify: docsify init .
Serve your site locally: docsify serve .

Note that docsify init . will create a new index.html for your site, overwriting the index.html currently in the directory. The generated index.html is your bog standard standard HTML page, except that it pulls in Docsify stylesheets and Javascript scripts and uses them to render your site on the fly from your markdown files.

See the sample index.html below, which includes explanatory comments. You’ll note that we’ve included and configured a search plugin to make searching your entire side super easy.

Also, here are some of the key settings you can configure in index.html:

Setting	Explanation
homepage	Sets the entry point of your site (`home.md` in the example), which is critical if your markdown directory isn’t using `README.md`
repo	Set it to the URL of your Github repo, or set to `true` if you’re using the “corner” plugin, as in the example. In either case you’ll see a little repo widget rendered in the upper right-hand corner of the site. Clicking it navigates to either the Github repo, or the `url` specified by the “corner” plugin.
relativePath	If you’re using relative paths like “./my_dir/yo” then you’ll need to set `relativePath` to `true` - otherwise Docsify will expect absolute URLs and your links won’t work
search	Self-explanatory search plugin configuration
Mermaid plugin	To support Mermaid diagrams, all we have to do is include the Mermaid Javascript module and script, here done toward the bottom of index.html.

Sample index.html for Docsify

<!--Sample index.html-->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Awesome Docs Site</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">

  <!-- Docsify themes -->
  <!--light-->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
  <!--dark-->
  <!-- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css"> -->

</head>
<body>
  <div id="app">Rendering docs...</div>
  <script>
    window.$docsify = {
      // How deep to nest the auto-generated TOC in the sidebar
      subMaxLevel: 3,

      // Name of site to show in sidebar
      name: 'My Awesome Wiki',

      // Set to 'true' if using the 'corner' plugin, or the URL of your Github repo
      repo: 'true',

      // If your homepage file isn't README.md
      homepage: 'home.md',

      // Useful if your markdown links are relative (e.g. './path/file.md')
      relativePath: true,

      // 'search' plugin configuration
      search: {
        // Expiration time, the default one day
        maxAge: 86400000, 
        paths: 'auto',
        placeholder: 'Type to search',
        noData: 'No Results!',
        // Headline depth, 1 - 6
        depth: 6,
        hideOtherSidebarContent: false,
      },

      // 'corner' plugin config
      corner: {
        url: "https://some-gitlab-url.example.org",
        target: "_blank",
        icon: "gitlab",
        background: "#064787"
      },
      plugins: [
        // 
      ]
    }
  </script>
  
  <!-- Docsify v4 -->
  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
  
  <!-- Search plugin -->
  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
  
  <!-- Corner plugin -->
  <script src="//cdn.jsdelivr.net/npm/docsify-corner/dist/docsify-corner.min.js"></script>

  <!-- Mermaid plugin -->
  <script type="module">
    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
    mermaid.initialize({ startOnLoad: true });
    window.mermaid = mermaid;
  </script>
  <script src="//unpkg.com/[email protected]/dist/docsify-mermaid.js"></script>
</body>
</html>

See how easy that was? Docsify is a great way to quickly render a website from your markdown files. See the Docsify documentation for more information on how to customize your site.

Enjoy your new Docsify site! 🎉

notes hugo hosting github gitlab vue markdown

Render a markdown site with Docsify

How about Docsify?

Sample index.html for Docsify

Ty Walls

Digital Construction Worker

Related