mirror of
https://github.com/litruv/Docs-Viewer.git
synced 2026-09-10 10:09:46 +10:00
Port Docs-Viewer to slatehtml as the docs-viewer package.
Replace the classic DOM shell with slate widgets, markdown→slate rendering, and a CI index build that uses build-docs.cjs.
This commit is contained in:
288
README.md
288
README.md
@@ -1,247 +1,83 @@
|
||||
# Docs Viewer
|
||||
|
||||
A modern, accessible documentation viewer for Markdown files with live search, navigation, and mobile support.
|
||||
Static documentation viewer built on **slatehtml** + **slatehtml-ui**: panel shell, live search, wiki links, and markdown as slate blocks (inline via `slate-rich-text`).
|
||||
|
||||
## Features
|
||||
## Install (consumer sites)
|
||||
|
||||
- 🔍 **Live search** with keyboard shortcuts (Alt+S) and result caching
|
||||
- 📱 **Mobile-friendly** responsive design with focus trap
|
||||
- 🎯 **Keyboard navigation** support (arrow keys, Enter, Escape)
|
||||
- 📑 **Auto-generated document outline** with collapsible headers
|
||||
- 🔗 **Wiki-style internal linking** with `[[Page Title]]` syntax
|
||||
- 🖨️ **Print-friendly** styling
|
||||
- ♿ **ARIA-compliant accessibility** (aria-current, role attributes, focus management)
|
||||
- 🌙 **Dark theme** with CSS custom properties
|
||||
- ⚡ **Performance optimized** with document caching and lazy loading
|
||||
- 📊 **Loading indicators** with animated progress bars
|
||||
|
||||
|
||||
## Screenshots
|
||||
|
||||
<p align="center">
|
||||
<img alt="Home" title="Home Page" src="https://github.com/user-attachments/assets/eb353607-7ce2-47fd-be87-479d9bbdac5c" height="300" />
|
||||
<img alt="Mobile UI" title="Mobile View" src="https://github.com/user-attachments/assets/b6157ec9-519a-47b6-b487-d5447f599027" height="300" />
|
||||
<br/>
|
||||
<img alt="Search" title="Live Search" src="https://github.com/user-attachments/assets/4ae9b7f7-2d99-4668-b6f5-5bd52c135e26" height="300" />
|
||||
<img alt="Outline" title="Document Outline Sidebar" src="https://github.com/user-attachments/assets/e2d58aa1-e297-4b7e-bec1-d3be5f69f45d" height="300" />
|
||||
<img alt="Print" title="Print-Friendly View" src="https://github.com/user-attachments/assets/a840be73-ca93-46c6-9fbe-5d498c2c3525" height="300" />
|
||||
</p>
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
npm install github:litruv/Docs-Viewer#slatehtml
|
||||
# peers / siblings as needed:
|
||||
npm install slatehtml slatehtml-ui
|
||||
```
|
||||
|
||||
2. Copy the example configuration:
|
||||
```bash
|
||||
cp example.index.json index.json
|
||||
```
|
||||
Then modify `index.json` with your site's metadata, author info, and social links.
|
||||
|
||||
3. Create your documentation structure:
|
||||
```
|
||||
docs/
|
||||
├── images/ # Place images here
|
||||
├── index.md # Main landing page
|
||||
└── ... other .md files
|
||||
```
|
||||
|
||||
4. Build the documentation index:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
This will scan your docs folder and update `index.json` with the document structure.
|
||||
|
||||
5. Start the development server:
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
### File Organization
|
||||
|
||||
- Place all documentation files in the `docs/` directory
|
||||
- Store images and video in `docs/images/`
|
||||
- Use `.md` extension for Markdown files
|
||||
|
||||
### Markdown Files
|
||||
|
||||
Each Markdown file can include YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Page Title
|
||||
description: Page description
|
||||
sort: 1 # Optional: controls sidebar order
|
||||
thumbnail: images/thumb.png # Optional: for OG images
|
||||
---
|
||||
|
||||
# Content starts here
|
||||
```
|
||||
|
||||
### Folder Structure
|
||||
|
||||
To create sections, make a folder and add a matching Markdown file:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── getting-started/
|
||||
│ ├── getting-started.md # Folder index
|
||||
│ ├── installation.md
|
||||
│ └── configuration.md
|
||||
└── index.md
|
||||
```
|
||||
|
||||
## Special Features
|
||||
|
||||
### Wiki Links
|
||||
|
||||
Use double brackets for internal links:
|
||||
```markdown
|
||||
[[Page Title]]
|
||||
[[Page Title|Custom Text]]
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
Store images in `docs/images/` and reference them:
|
||||
```markdown
|
||||
|
||||
# or
|
||||
![[picture.png]]
|
||||
```
|
||||
|
||||
### Headers
|
||||
|
||||
Headers are automatically added to the right sidebar outline and are collapsible.
|
||||
|
||||
## Development
|
||||
|
||||
### Recommended Editor
|
||||
|
||||
We recommend using [Obsidian.md](https://obsidian.md) as your editor for the documentation files. The `docs/.obsidian` directory includes a custom plugin that provides enhanced editing features:
|
||||
|
||||
- Displays page titles in the file explorer instead of filenames
|
||||
- Shows frontmatter-defined sort order in the file list
|
||||
- Automatically updates file ordering based on the `sort` property
|
||||
- Makes folder and document organization more intuitive
|
||||
|
||||
To use the plugin:
|
||||
1. Open the `docs` folder as an Obsidian vault
|
||||
2. The plugin will be automatically loaded
|
||||
3. The file explorer will now show your document titles and sorting order
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── docs/ # Documentation files
|
||||
├── js/ # Application modules
|
||||
│ ├── EventBus.js # Pub-sub event system
|
||||
│ ├── IndexService.js # Document index management
|
||||
│ ├── SearchService.js # Search with caching
|
||||
│ ├── DOMService.js # DOM manipulation & accessibility
|
||||
│ ├── DocumentService.js # Markdown loading & caching
|
||||
│ ├── NavigationService.js # Browser history handling
|
||||
│ └── Documentation.js # Main orchestrator
|
||||
├── build-docs.js # Documentation builder
|
||||
├── index.html # Main viewer
|
||||
└── styles.css # Styling
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
The application uses a modular ES6 architecture with:
|
||||
|
||||
- **EventBus**: Pub-sub pattern for decoupled communication between services
|
||||
- **Services**: Single-responsibility modules for search, DOM, documents, and navigation
|
||||
- **Caching**: LRU caches for search results (50 entries) and documents (20 entries)
|
||||
- **Lazy Loading**: Images use `loading="lazy"` for improved performance
|
||||
|
||||
|
||||
### Building
|
||||
|
||||
The build process:
|
||||
1. Scans the `docs/` directory
|
||||
2. Edits `index.json` with document metadata
|
||||
|
||||
A GitHub Actions workflow is included that automatically:
|
||||
- Runs on every push to the master branch
|
||||
- Executes the build process
|
||||
- Commits and pushes any changes to `index.json`
|
||||
- Ensures your documentation index stays in sync with your content
|
||||
|
||||
This means you can edit your documentation directly on GitHub, and the index will be automatically updated.
|
||||
|
||||
If you don't want to use Github actions, you can use npm run build
|
||||
|
||||
### Cloudflare Pages
|
||||
|
||||
1. Create a new repository on GitHub.
|
||||
2. Push your code to the repository.
|
||||
3. Go to [Cloudflare Pages](https://pages.cloudflare.com/) and connect your GitHub repository.
|
||||
4. Configure the build settings:
|
||||
- **Production branch:** `main` (or your main branch name)
|
||||
- **Build command:** Leave empty
|
||||
- **Build output directory:** `/` (root)
|
||||
5. Save and deploy.
|
||||
|
||||
#### Optional: Cloudflare Worker for OG/Twitter Tags
|
||||
|
||||
For improved SEO and social sharing, you can use a Cloudflare Worker to dynamically generate OG/Twitter tags.
|
||||
|
||||
1. Create a new Cloudflare Worker using the code in `cloudflare-worker.js`.
|
||||
2. Set the `SITE_URL` environment variable to where your site will be located, e.g., `https://example.com/docs/`
|
||||
3. Set the `DOCS_URL` environment variable to the URL where your documentation files are hosted (usually your Cloudflare Pages URL).
|
||||
4. Configure a route in your Cloudflare account to route all requests to your Cloudflare Pages site through the worker.
|
||||
|
||||
## Configuration
|
||||
|
||||
### index.json
|
||||
Local sibling checkout:
|
||||
|
||||
```json
|
||||
{
|
||||
"defaultPage": "home",
|
||||
"showDocsLink": true,
|
||||
"metadata": {
|
||||
"title": "Site Title",
|
||||
"description": "Site description",
|
||||
"site_name": "Documentation"
|
||||
},
|
||||
"author": {
|
||||
"name": "Author Name",
|
||||
"role": "Role",
|
||||
"socials": [
|
||||
{
|
||||
"icon": "fab fa-github",
|
||||
"url": "https://github.com/username",
|
||||
"title": "GitHub"
|
||||
}
|
||||
]
|
||||
"dependencies": {
|
||||
"docs-viewer": "file:../Docs-Viewer",
|
||||
"slatehtml": "file:../slatehtml",
|
||||
"slatehtml-ui": "file:../slatehtml/packages/slatehtml-ui"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `showDocsLink` option controls whether a "Docs" link is shown in the UI navigation. Set to `false` to hide it.
|
||||
## App usage
|
||||
|
||||
The build process generates the documents part for `index.json`
|
||||
## Contributing
|
||||
```html
|
||||
<body>
|
||||
<slate-docs-viewer index="./index.json"></slate-docs-viewer>
|
||||
<script type="module" src="./main.js"></script>
|
||||
</body>
|
||||
```
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Submit a pull request
|
||||
```js
|
||||
import "slatehtml";
|
||||
import "slatehtml-ui/app-bar";
|
||||
import "slatehtml-ui/icon";
|
||||
import "slatehtml-ui/text-field";
|
||||
import "slatehtml-ui/side-bar";
|
||||
import "slatehtml-ui/text";
|
||||
import "slatehtml-ui/progress";
|
||||
import "slatehtml-ui/alert";
|
||||
import "slatehtml-ui/divider";
|
||||
import { configure } from "slatehtml-ui/configure";
|
||||
import { fontAwesomeSvg } from "slatehtml-ui/icons/fontawesome";
|
||||
import { mountDocs } from "docs-viewer";
|
||||
import "docs-viewer/prose.css";
|
||||
|
||||
## Dependencies
|
||||
configure({ icons: fontAwesomeSvg });
|
||||
await mountDocs("slate-docs-viewer");
|
||||
```
|
||||
|
||||
- [marked.js](https://marked.js.org/) - Markdown parsing
|
||||
- [highlight.js](https://highlightjs.org/) - Syntax highlighting
|
||||
- [Font Awesome](https://fontawesome.com/) - Icons
|
||||
Vite needs the UMC plugin with UI + this package’s `src`:
|
||||
|
||||
## License
|
||||
```js
|
||||
import { umc } from "slatehtml/umc/vite";
|
||||
import { createRequire } from "node:module";
|
||||
import { dirname, join } from "node:path";
|
||||
|
||||
MIT License - see LICENSE file for details.
|
||||
const require = createRequire(import.meta.url);
|
||||
const uiSrc = join(dirname(require.resolve("slatehtml-ui/package.json")), "src");
|
||||
const docsSrc = join(dirname(require.resolve("docs-viewer/package.json")), "src");
|
||||
|
||||
export default {
|
||||
plugins: [umc({ roots: [uiSrc, docsSrc] })],
|
||||
};
|
||||
```
|
||||
|
||||
## Develop this repo
|
||||
|
||||
```bash
|
||||
npm install # expects ../slatehtml checkout
|
||||
npm run build:index
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Content contract
|
||||
|
||||
Same as before:
|
||||
|
||||
- `docs/**/*.md` + YAML frontmatter
|
||||
- `index.json` metadata; `documents` from `npm run build:index`
|
||||
- Wiki `[[Page Title]]`, embeds `![[image.png]]`
|
||||
|
||||
Reference in New Issue
Block a user