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.