Building Interactive Documentation Sites with ljbisheng (keDoc)

In long‑term projects, keeping technical documentation up‑to‑date is essential for future developers, and using web technologies makes docs more expressive and interactive.

The keDoc documentation library is built on ljbisheng, a React framework that converts convention‑based markdown files into a single‑page React site. It uses markdown-it for rendering markdown and custom plugins for extensions.

Key features include managing submodules with git submodule, a theme designed for technical docs with customizable navigation, automatic route generation, markdown syntax support with code highlighting, React code block conversion, and automated packaging and publishing.

Getting started :

Step 1 – Install dependencies: npm install --save-dev ljbisheng Step 2 – Add scripts to package.json (using -c to specify the config file):

{
  "scripts": {
    "start": "ljbisheng start -c ./site/bisheng.config.js",
    "build": "ljbisheng build -c ./site/bisheng.config.js"
  }
}

Step 3 – Create bisheng.config.js to configure the server, source markdown files, lazy loading, theme path, HTML template, plugins, and custom webpack settings.

module.exports = {
  port: 8000,
  source: ['./docs', 'README.md'],
  lazyLoad: true,
  theme: './site/theme/',
  htmlTemplate: './site/theme/static/template.html',
  plugins: [
    'bisheng-plugin-description',
    'bisheng-plugin-toc?maxDepth=2',
    'bisheng-plugin-react?lang=__react',
    'bisheng-plugin-ljdoc'
  ],
  webpackConfig(config) {
    return config;
  }
};

Parameter explanations:

port : server listening port.

source : directories of markdown files.

lazyLoad : when true, markdown data is loaded lazily as promises.

theme : path to the theme (or npm package).

htmlTemplate : HTML template for generated pages.

plugins : list of plugins following webpack‑loader conventions.

webpackConfig : function to modify internal webpack configuration.

Run npm run start to launch the dev server at 0.0.0.0:8000, which automatically renders markdown files as interactive pages.

Step 4 – Define default page routes based on the project’s directory structure.

Step 5 – Create a theme with the following structure:

theme/
├── index.js
├── static/
│   └── style.css
└── template/
    ├── NotFound.jsx
    └── Template.jsx

File explanations:

index.js : entry point defining routes (similar to react‑router) and theme‑specific configuration.

static : global stylesheet applied with higher priority.

template : HTML templates and React components; NotFound.jsx handles 404 routes, Template.jsx receives parsed markdown data as props.

Step 6 – Implement plugins. A plugin is an npm package with a specific directory layout (e.g., lib/browser.js and lib/node.js). Example bisheng-plugin-highlight adds syntax highlighting to code blocks:

'use strict';
var React = require('react');
var JsonML = require('jsonml.js/lib/utils');
module.exports = function() {
  return {
    converters: [[
      function(node) { return JsonML.isElement(node) && JsonML.getTagName(node) === 'pre'; },
      function(node, index) {
        var attr = JsonML.getAttributes(node);
        return React.createElement('pre', {key: index, className: 'language-' + attr.lang},
          React.createElement('code', {dangerouslySetInnerHTML: {__html: attr.highlighted}}));
      }
    ]]
  };
};

The browser.js runs in the browser, while node.js processes markdown data on the server.

Common plugins include:

bisheng-plugin-highlight – code syntax highlighting.

bisheng-plugin-description – extracts description from markdown.

bisheng-plugin-toc – generates a table of contents.

bisheng-plugin-react – converts markdown React code to React elements.

bisheng-plugin-ljdoc – specific to the keDoc documentation.

Underlying workflow :

Load bisheng.config.js and theme configuration, generate index.html and entry files.

Parse markdown files into a JSON‑ML tree using mark‑twain and apply plugins sequentially.

Generate route information from the theme’s routing config.

When a URL matches a route, load the corresponding markdown data, pass it to the configured React component, and render it.

The process is divided into two stages: (1) parsing markdown data (including plugin processing) and (2) rendering React components with the parsed data.

Finally, the guide summarizes that keDoc follows a “convention over configuration” philosophy to simplify documentation site setup while retaining flexibility, and suggests considering what should be convention‑based versus configurable when designing frameworks.