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
doc	—	controlled full repo path of the document to show (e.g. 'Platforms/01-Foo.md'); wins over the ?doc= query and lets a host-app router switch docs while the component stays mounted. Pair with useGithubDocList.

Custom navigation (useGithubDocList)

useGithubDocList is a named-export React hook that lists the top-level Markdown documents under path, for building your own navigation (e.g. an inline menu of section pages) outside the sidebar.

import GithubDocs, { useGithubDocList } from 'gramene-githubdocs'

function PlatformsMenu() {
  const docs = useGithubDocList({ org: 'warelab', repo: 'oryza-19k-rgp', path: 'Platforms' })
  // docs: [{ fullPath, label, title }]  (title is the front-matter title, lazily filled)
  return docs.map((d) => (
    <a key={d.fullPath} href={`/platforms?doc=${encodeURIComponent(d.fullPath)}`}>
      {d.title || d.label}
    </a>
  ))
}

Returns [{ fullPath, label, title }] ordered the same way GithubDocs orders a folder level (by sort; title starts null and upgrades to the front-matter title: when fetched). Link each entry to a GithubDocs route with ?doc=<encodeURIComponent(fullPath)> and feed the same path back through the doc prop so the view switches even when it stays mounted. Shares GithubDocs' tree/content caches. Accepts { org, repo, path, branch, sort, date }.

Single document (no navigation)

GithubDoc is a named export that renders one Markdown file from a repo — no tree, no pager. Use it to embed a single document (an overview, an announcement) inside another page. Optionally it shows an in-document table of contents that navigates between the document's own sections.

import { GithubDoc } from 'gramene-githubdocs'

<GithubDoc
  org="warelab"
  repo="oryza-19k-rgp"
  path="Start here/01-Overview.md"   // path to the .md file in the repo
  branch="main"
  toc                                 // sticky "On this page" section nav
  offset={100}                        // px of fixed page chrome above the doc
/>

prop	default	description
org	—	GitHub owner/org (required)
repo	—	repository name (required)
path	—	path to the .md file in the repo (required)
branch	'main'	branch/ref (falls back to master)
showTitle	false	render the front-matter title: as a heading above the body (most docs carry their own # H1)
toc	false	show a sticky sidebar table of contents of the document's headings; clicking scrolls to a section and the current section is highlighted (scroll-spy). The TOC header is the document's front-matter title: (bold) as a link that scrolls back to the top
tocLevels	[2, 3]	heading levels to include in the TOC
tocHeading	'On this page'	fallback TOC header used only when the document has no front-matter title:
renderTitle	t => t	transform the document title before rendering (in the showTitle heading and the TOC head) — e.g. to italicize a genus name; receives the title string, returns a React node
offset	0	px of fixed page chrome (e.g. a sticky navbar) above the doc; sets the TOC's sticky top and the scroll-to-heading offset
className	''	extra class name on the wrapper

Relative images resolve against the file's own directory; relative links to other repo files open their GitHub blob page (there's no tree to navigate in-place). Rendering fails quiet — an unreachable document renders nothing rather than breaking its host page. Shares the same CSS as GithubDocs.

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.