gramene-githubdocs

A React component that renders a tree of Markdown files straight from a GitHub repository. Subdirectories become navigation levels: the whole repo tree is pulled in one Git-Trees API call, the .md files under path are reassembled into a folder hierarchy, and selecting a file renders it in a reading pane.

Usage

import GithubDocs from 'gramene-githubdocs'

<GithubDocs
  org="warelab"
  repo="release-notes"
  path="oryza19k-guides"   // root the view at a subdirectory ('' = repo root)
  branch="main"
  heading="User Guide"
/>

Props

| prop | default | description | | --- | --- | --- | | org | — | GitHub owner/org (required) | | repo | — | repository name (required) | | path | '' | base directory to root the docs at; '' = repo root | | branch | 'main' | branch/ref (falls back to master) | | heading | 'Documentation' | sidebar title + root breadcrumb/level label | | offset | 0 | px of page chrome above the component, so it can size itself to calc(100vh - offset) and scroll internally (also auto-measured) | | summaryNames | ['index','readme','overview','summary'] | filenames (cleaned, case-insensitive) treated as a folder's summary document for the "Up a level" view | | sort | 'order' | 'order' = by 01- numeric prefix then alphabetically; 'date' = newest-first by the ---YYYY-MM-DD suffix, hiding entries dated after date (good for release notes) | | date | today | reference date for sort="date" future-hiding; entries dated after it are not shown | | ifEmpty | "No Markdown documents found in this location." | message shown when the location has no (visible) documents |

Features

• Subdirectories become collapsible navigation levels; order by an optional 01- numeric prefix (default) or, with sort="date", newest-first by a ---YYYY-MM-DD filename suffix (release-notes style, hides future-dated docs).
• Reading pane with Prev / Next within the current folder and an Up a level control that shows the parent level's summary document (or an auto-generated section overview when none exists).
• Clickable breadcrumbs, ?doc= deep-links, relative-image rewriting to raw GitHub URLs, and in-place navigation for relative links to other docs.
• GitHub-style automatic heading IDs (via rehype-slug), so in-page anchor links ([Top](#overview)) resolve without any {#id} heading syntax.
• Front-matter title: sets both the rendered heading and the sidebar label (front-matter is fetched eagerly so sidebar titles don't depend on filenames); falls back to the de-slugified filename. Asset dirs (images, assets, …) and _/.-prefixed entries are ignored.
• Styling is themeable via the CSS variables on .ghdocs (see css/githubDocs.css).

Build

npm install
npm run build      # → es/ (ESM) + lib/ (CJS); css/ ships as-is

npm start runs a Vite demo against the live warelab/release-notes repo.