@hacknock/lobster-wiki

v0.1.0

Published

a month ago

Wiki/multi-page site extension for lobster.js — Markdown-driven, zero-config

0High
0Medium
0Low

kyome

lobster markdown wiki multi-page static-site no-build zero-dependency css-first browser esm typescript

lobster-wiki

Markdown-driven wiki / multi-page site extension for lobster.js.

Demo →

lobster-wiki turns a folder of Markdown files into a wiki-style site — sidebar navigation, page routing, auto-generated table of contents — with almost no code beyond the Markdown itself.

Quick Start

Create a project with this structure:

my-wiki/
  index.html
  wiki.config.json
  nav.md
  content/
    intro.md
    guide.md

Write wiki.config.json:

{
  "title": "My Wiki",
  "navigation": "./nav.md",
  "footer": "./footer.md",
  "defaultPage": "intro",
  "tableOfContents": true
}

Write nav.md as a nested list with ?page= links:

- Getting Started
  - [Introduction](?page=intro)
  - [Guide](?page=guide)

Write a minimal index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Wiki</title>
    <link rel="stylesheet" href="https://hacknock.github.io/lobster-wiki/style.css" />
  </head>
  <body>
    <script type="module">
      import { initWiki } from "https://hacknock.github.io/lobster-wiki/lobster-wiki.js";
      initWiki("./wiki.config.json");
    </script>
  </body>
</html>

Write your content pages in content/ and serve with any static file server.

Installation

CDN

The latest build is available via GitHub Pages — see the import URL in the Quick Start above. Or download lobster-wiki.js from the releases page and host it yourself.

npm

npm install @hacknock/lobster-wiki

import { initWiki } from "@hacknock/lobster-wiki";
initWiki("./wiki.config.json");

Features

SPA routing — ?page=slug query parameters with browser history support
Sidebar navigation — loaded from a Markdown file (nav.md) with active link highlighting
Auto-generated table of contents — builds an "On this page" section from headings (h2-h4)
Shared header / footer — specify via .md file path in config
Hash routing — optional "routing": "hash" mode for file:// protocol compatibility
Responsive — sidebar collapses on mobile, TOC hides on narrow screens
CSS-first — wiki layout uses lbw-* classes; content uses lobster.js lbs-* classes

Configuration

All options are defined in wiki.config.json:

| Key | Description | Default | | ----------------- | -------------------------------------------------------------------------------------- | ---------------- | | title | Site title (used in <title>) | — | | navigation | Path to sidebar navigation Markdown file (required) | — | | header | Path to header Markdown file | — | | footer | Path to footer Markdown file | — | | contentDir | Directory containing page Markdown files | ./content/ | | defaultPage | Default page slug when no ?page= is specified | intro | | tableOfContents | Enable auto-generated table of contents (true or { "minLevel": 2, "maxLevel": 4 }) | false | | routing | Routing mode: query or hash | query | | lobsterUrl | URL to lobster.js | GitHub Pages CDN |

Development

This project uses npm (declared via devEngines; requires >=11.10.0 for the min-release-age setting in .npmrc, which blocks installation of package versions less than 7 days old as a supply-chain mitigation).

npm ci               # Install dependencies (uses package-lock.json)
npm run build        # Build dist/lobster-wiki.js
npm run build:docs   # Build and copy to docs/ for GitHub Pages

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme