Express-documentation NPM

screenshot

How To Use

To install this package, you'll need Node.js (which comes with npm) installed on your computer. From your command line:

# Using npm
$ npm install express ejs express-documentation

# Using yarn
$ yarn add express ejs express-documentation

Documentation

Express Docs should be used as middleware in Express.js at the path where you want your docs to be located at. This translates to using the app.use method of your Express.js app and setting the location path as the first argument and the executed expressDocs method as the second property with the app variable as a parameter.

app.use("/docs", expressDocs(app));

This will use the default parameters for Express Docs:

Parameter	Default Value	Accepted Object Types
📲 Title	`productName`; `name`; `"Documentation"`	`string`
🎨 Favicon	`"./favicon.ico"`	`path`; `URL`
⏱️ Logo	`"./logo.png"`	`path`; `URL`
👨‍💻 Directory	`"./docs"`	`path`

All of these values should be modified like this:

app.use("/docs", expressDocs(app, {
  title: "Express Docs Demo",
  favicon: "./assets/favicon.ico",
  logo: "./assets/logo.png" || "https://raw.githubusercontent.com/DinoscapeProgramming/Remote-Control/main/server/assets/logo.svg",
  directory: "./assets/docs" || "https://raw.githubusercontent.com/DinoscapeProgramming/Remote-Control/main/server/assets/favicon.ico"
}));

Additional options include: | Optional Parameter | | --- | | 🥷 Security (Content Security Policy) | | 🧭 Analytics | | 📲 Custom Markdown Parser | | 🎨 Custom HTML (Head or Body) | | ⏱️ Custom Code | | 👨‍💻 Custom Style | | 💱 Extensions |

app.use("/docs", expressDocs(app, {
  options: {
    security: {
      csp: `` // --> content security policy header
    },
    analytics: ``, // --> Google Analytics tracking id
    customMarkdownParser: () => {}, // --> return value in plain HTML
    customHTML: {
      head: ``,
      body: ``
    }, // --> plain HTML,
    customCode: () => {}, // --> JavaScript function
    customStyle: ``, // --> plain CSS
    extensions: [
      {
        setup: () => {}, // --> executed on function call
        middleware: () => {} // --> executed on returned function call
      }
    ]
  }
}));

The default markdown parser uses Marked and all contents of the markdown parser, no matter which, are being sanitized with DOMPurify.

Example Documentation with Dark Mode

To build and open your own installable, you'll need Node.js (which comes with npm) installed on your computer.

const express = require("express");
const app = express();
const expressDocs = require("express-docs");

app.use("/", expressDocs(app, {
  title: "Express Docs Demo",
  favicon: "./favicon.ico",
  logo: "./logo.png",
  directory: "./docs",
  options: {
    security: {
      csp: "default-src 'self'; script-src 'self' 'unsafe-inline';"
    },
    analytics: "UA-XXXXXXX-X",
    customMarkdownParser: (markdownContent) => `
      <div style="font-family: system-ui">${markdownContent}</div>
    `,
    customHTML: {
      head: `
        <meta name="description" content="Express Docs Example">
      `,
      body: `
        <div style="
          font-family: system-ui;
          position: fixed;
          right: 7.5px;
          padding-top: calc(100vh - 27.5px);
        ">Made by Express Docs</div>
     `
    },
    customCode: () => {
      console.log("This documentation page was made by Express Docs.");
    }
    customStyle: `
      body: {
        background-color: #1c1c1c;
        invert(95%) hue-rotate(180deg);
      }
    `,
    extensions: [
      require("express-docs-themes")("translucence")
    ]
  }
}));

Note If you're using Linux Bash for Windows, see this guide or use node from the command prompt.
If you're not using Windows, change the ./node_modules/express-documentation/package.json file accordingly to this guide.