onedoc

README

onedoc

A tool to help render a folder of Markdown docs into a single self-contained HTML page. Every doc becomes a hidden <section> and a small client-side router shows one at a time, so it reads like a multi-page site but ships as one portable file (CSS and JS inlined). It works offline, and browser find (Ctrl/Cmd + F) searches everything at once.

Features: light/dark themes, syntax highlighting, per-page table of contents with scrollspy, copy-able code blocks, keyboard/skip-link accessibility, and a <noscript> fallback that reveals all content as one long page. Zero runtime dependencies in the output; one build-time dependency (goldmark).

Install

go install github.com/gnikyt/onedoc/cmd/onedoc@latest

Use

Create an onedoc.json next to your Markdown, then run:

onedoc # reads ./onedoc.json
onedoc -config docs/onedoc.json

sourceDir and output are resolved relative to the config file.

Config

{
  "site": {
    "title": "My Project",
    "short": "mp",                 // Logo text + <title> prefix
    "version": "v1",               // Optional pill in the header
    "repo": "https://github.com/you/mp", // Optional header link
    "description": "One-line meta description."
  },
  "sourceDir": ".",                // Markdown root, relative to this file
  "output": "index.html",          // Output file, relative to this file
  "home": "HOME.md",               // Optional home content: a .md path OR inline Markdown
  "customCSS": "theme.css",        // Optional CSS inlined after the defaults
  "groups": [
    {
      "title": "Getting Started",
      "hideCards": true,           // Omit this group from the home card grid
      "items": [
        { "title": "Overview", "href": "#top" },
        {
          "title": "Guide",
          "source": "GUIDE.md",    // Relative to sourceDir
          "anchor": "guide",       // In-page section ID
          "blurb": "Card description on the home view."
        },
        {
          "title": "Install",
          "source": "../README.md",
          "section": "Installation", // Extract just this "## Installation" block
          "anchor": "install",
          "blurb": "..."
        },
        {
          "title": "Advanced",       // A branch: no source, just nests children
          "children": [
            { "title": "Tuning", "source": "TUNING.md", "anchor": "tuning", "blurb": "..." }
          ]
        }
      ]
    }
  ]
}

Notes:

• Sections. section pulls a single ## <name> block out of a larger file (e.g. a project README) and promotes its headings, so content isn't duplicated.
• Cross-links. Links to a doc's Markdown file (e.g. GUIDE.md) are rewritten to its in-page anchor automatically.
• Home. home renders at the top of the landing view, above the card grid. It's a file when the value is a bare path ending in .md (read from sourceDir), otherwise the value is treated as inline Markdown — handy for a one-line intro without a dedicated file.
• Nesting. Any item may carry children for a multi-level sidebar; the branch expands/collapses and auto-opens to the active page. A branch with no source/href is just a label. Nested Markdown files (e.g. "source": "guides/x.md") work regardless of nesting.
• Theming. The default theme is driven by CSS variables; a customCSS file is inlined after the defaults, so overriding --accent, --bg, etc. reskins the whole site in a few lines.

Develop

go test ./...
go run ./cmd/onedoc -config path/to/onedoc.json

Templates and assets live in templates/ and assets/ and are embedded into the binary at build time.

Documentation

Index

• func Build(configPath string) error
• type Config
• type Group
• type Item
• type Site

Functions

func Build

func Build(configPath string) error

Build renders the site described by the config file at configPath, writing the single HTML page to the configured output.

Types

type Config

type Config struct {
	Site      Site    `json:"site"`
	SourceDir string  `json:"sourceDir"` // Markdown root, relative to the config file. Default ".".
	Output    string  `json:"output"`    // Output file, relative to the config file. Default "index.html".
	Home      string  `json:"home"`      // Optional home content: a ".md" file path (relative to SourceDir) or inline Markdown.
	CustomCSS string  `json:"customCSS"` // Optional CSS file inlined after the defaults, relative to the config file.
	Groups    []Group `json:"groups"`
}

Config is the whole site description, loaded from a JSON file.

type Group

type Group struct {
	Title     string `json:"title"`
	HideCards bool   `json:"hideCards"` // Omit this group from the home card grid.
	Items     []Item `json:"items"`
}

Group is a titled cluster of sidebar items.

type Item

type Item struct {
	Title    string `json:"title"`
	Source   string `json:"source"`   // Markdown file, relative to SourceDir.
	Section  string `json:"section"`  // Extract just this "## <section>" block from Source.
	Anchor   string `json:"anchor"`   // In-page section id this doc renders under.
	Href     string `json:"href"`     // Explicit link target; used when Anchor is empty.
	Blurb    string `json:"blurb"`    // Card description on the home view.
	Children []Item `json:"children"` // Nested sidebar entries.
}

Item is a single sidebar entry. A doc entry sets Source (+ optional Section) and Anchor; a plain link sets Href instead; a branch sets neither and nests Children. Any item may also carry Children to build a multi-level sidebar.

type Site

type Site struct {
	Title       string `json:"title"`
	Short       string `json:"short"`
	Version     string `json:"version"`
	Repo        string `json:"repo"`
	Description string `json:"description"` // <meta name="description">
}

Site holds project-level metadata shown in the header and <head>.