Skip to content

README.md

Latest commit

 

History

History
63 lines (52 loc) · 2.94 KB

README.md

File metadata and controls

63 lines (52 loc) · 2.94 KB

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.