litruv/Docs-Viewer
1
0
Fork 0
mirror of https://github.com/litruv/Docs-Viewer.git synced 2026-07-24 02:36:07 +10:00
Code Issues Packages Projects Releases Wiki Activity

updated examples

Browse Source
This commit is contained in:
Litruv
2025-02-10 16:15:51 +11:00
parent bcf41a1fff
commit 3fff5766eb
2 changed files with 85 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
README.md
View File

@@ -13,14 +13,20 @@ A robust, modern documentation viewer built for rendering Markdown files with ad
## Quick Start ## Quick Start
### Development Setup ### Development Setup
[Fork this Repo](https://github.com/litruv/Docs-Viewer/fork)
[Fork this Repo](https://github.com/example/Docs-Viewer/fork)
#### Updating #### Updating
##### From GitHub ##### From GitHub
On your own repo, On your own repo,
1. Click Sync fork 1. Click Sync fork
2. Update branch 2. Update branch
##### From CLI ##### From CLI
```sh ```sh
git fetch upstream git fetch upstream
git merge upstream/master git merge upstream/master
@@ -34,31 +40,31 @@ Deploy anywhere that serves static files. For local development:
VSCode: VSCode:
[LiveServer](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) and hit start server in the docs-viewer directory [LiveServer](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) and hit start server in the docs-viewer directory
Rawdogging it with notepad: Command Line:
```sh ```sh
npx live-server npx live-server
``` ```
#### Cloudflare Pages
#### Cloudflare Pages 1. Create a new repository on GitHub.
2. Push your code to the repository.
1. Create a new repository on GitHub. 3. Go to [Cloudflare Pages](https://pages.cloudflare.com/) and connect your GitHub repository.
2. Push your code to the repository. 4. Configure the build settings:
3. Go to [Cloudflare Pages](https://pages.cloudflare.com/) and connect your GitHub repository. - **Production branch:** `main` (or your main branch name)
4. Configure the build settings: - **Build command:** Leave empty
* **Production branch:** `main` (or your main branch name) - **Build output directory:** `/` (root)
* **Build command:** Leave empty 5. Save and deploy.
* **Build output directory:** `/` (root)
5. Save and deploy.
##### Optional: Cloudflare Worker for OG/Twitter Tags ##### 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. 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`. 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, eg. `https://lit.ruv.wtf/docs/` 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). 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. 4. Configure a route in your Cloudflare account to route all requests to your Cloudflare Pages site through the worker.
## Project Structure ## Project Structure
@@ -72,13 +78,12 @@ For improved SEO and social sharing, you can use a Cloudflare Worker to dynamica
└── styles.css # Theme customization └── styles.css # Theme customization
``` ```
## Configuration ## Configuration
Configure your documentation site with a top-level index file named `index.json`. At minimum, include a `title`, a `defaultPage`, and a list of `documents`: Configure your documentation site with a top-level index file named `index.json`. At minimum, include a `title`, a `defaultPage`, and a list of `documents`:
```json ```json
{ {
"title": "My Documentation Site",
"defaultPage": "welcome", "defaultPage": "welcome",
"documents": [ "documents": [
{ {
@@ -90,7 +95,7 @@ Configure your documentation site with a top-level index file named `index.json`
} }
``` ```
> If you want to quickly get started, copy `example.index.json` to `index.json` in the project root of your own repository: > If you want to quickly get started, copy `example.index.json` to `index.json` in the project root:
```sh ```sh
cp example.index.json index.json cp example.index.json index.json
@@ -98,19 +103,12 @@ cp example.index.json index.json
Then adjust the `title`, `defaultPage`, and `documents` array to match your needs. Then adjust the `title`, `defaultPage`, and `documents` array to match your needs.
After placing your `index.json` in the project root, the application will:
1. Apply your site `title` to the browser tab and page header.
2. Load the `defaultPage` when no slug is specified in the URL.
3. Generate a navigation tree from the array of `documents`.
### Root Configuration Options ### Root Configuration Options
| Option | Type | Description | | Option | Type | Description | |
|---------------|--------|----------------------------------------------------------| | ------------- | ------ | -------------------------------------------------- | - |
| `title` | string | Title of your documentation site | | `defaultPage` | string | Slug of the page to show when no page is specified | |
| `defaultPage` | string | Slug of the page to show when no page is specified | | `documents` | array | Array of document or folder entries (see below) | |
| `documents` | array | Array of document or folder entries (see below) |
### Folder Organization ### Folder Organization
@@ -118,23 +116,18 @@ Folders can contain nested documents or subfolders. Mark a folder by setting `"t
```json ```json
{ {
"title": "My Documentation Site", "title": "Core Concepts",
"defaultPage": "welcome", "type": "folder",
"documents": [ "path": "docs/core-concepts/index.md",
"slug": "core-concepts",
"defaultOpen": true,
"icon": "fa-solid fa-book",
"color": "#01beef
"items": [
{ {
"title": "Core Concepts", "title": "Getting Started",
"type": "folder", "path": "docs/guides/getting-started.md",
"defaultOpen": true, "slug": "getting-started"
"icon": "fa-solid fa-book",
"path": "docs/core-concepts/index.md",
"slug": "core-concepts",
"items": [
{
"title": "Getting Started",
"path": "docs/guides/getting-started.md",
"slug": "getting-started"
}
]
} }
] ]
} }
@@ -142,72 +135,41 @@ Folders can contain nested documents or subfolders. Mark a folder by setting `"t
#### Folder Configuration Options #### Folder Configuration Options
| Option | Type | Description | | Option | Type | Description |
|-----------------|----------|----------------------------------------------------| | ------------- | -------- | -------------------------------------------------- |
| `type` | string | Set to `"folder"` for a directory node | | `title` | string | Display name of the folder |
| `title` | string | Display name of the folder | | `type` | string | Set to `"folder"` for a directory node |
| `path` | string? | Optional content file path | | `path` | string? | Optional content file path |
| `slug` | string | URL-friendly identifier; required if `path` exists| | `slug` | string | URL-friendly identifier; required if `path` exists |
| `items` | array | Nested documents or folders | | `defaultOpen` | boolean? | Automatically expand this folder in the sidebar |
| `defaultOpen` | boolean? | Automatically expand this folder in the sidebar | | `icon` | string? | Custom Font Awesome classes |
| `icon` | string? | Custom Font Awesome classes | | `items` | array | Nested documents or folders |
## Metadata Configuration ## Metadata Configuration
> To be used with the cloudflare-worker.js
You can include a "metadata" object in `index.json` to provide: You can include a "metadata" object in `index.json` to provide:
- Site-wide title and short description - Site-wide title and short description
- Thumbnail for social sharing - Thumbnail for social sharing
- Display name for your site - Display name for your site
```json ```json
"metadata": { "metadata": {
"title": "Litruv / Documentation", "site_name": "MyDocs"
"description": "Documentation for Litruv's plugins", "description": "Documentation for my project",
"thumbnail": "img/og-image.png", "thumbnail": "img/og-image.png",
"site_name": "Litruv"
} }
``` ```
#### Metadata Configuration Options #### Metadata Configuration Options
| Option | Type | Description | | Option | Type | Description |
|---------------|--------|----------------------------------------------------------| | ------------- | ------ | ------------------------------------------- |
| `title` | string | Title of your documentation site | | `site_name` | string | Display name for your site |
| `description` | string | Description of your documentation site | | `description` | string | Description of your documentation site |
| `thumbnail` | string | URL to a thumbnail image for social sharing | | `thumbnail` | string | URL to a thumbnail image for social sharing |
| `site_name` | string | Display name for your site |
## Additional Author Info
You can add an "author" object in your `index.json` to display your name, role, and social links:
```json
"author": {
"name": "Litruv",
"role": "Dev/Tech Artist @MatesMedia",
"socials": [
{
"icon": "fab fa-github",
"url": "https://github.com/Litruv",
"title": "GitHub - Litruv"
},
{
"icon": "fab fa-youtube",
"url": "https://www.youtube.com/c/Litruv",
"title": "YouTube - Litruv"
}
]
}
```
## Technology Stack
Built with modern web technologies and carefully selected dependencies:
- [marked](https://github.com/markedjs/marked) - Markdown processing
- [highlight.js](https://highlightjs.org/) - Syntax highlighting
- [Font Awesome](https://fontawesome.com/) - UI iconography
## License ## License
@@ -216,3 +178,4 @@ Released under the MIT License. See [LICENSE](LICENSE) for details.
## Contributing ## Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details. Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

51
example.index.json
View File

@@ -1,60 +1,61 @@
{ {
"defaultPage": "welcome", "defaultPage": "home",
"customCSS": "custom/theme.css",
"metadata": { "metadata": {
"description": "Documentation for Litruv's plugins", "title": "Project Documentation",
"thumbnail": "img/og-image.png", "description": "Comprehensive documentation for various projects.",
"site_name": "Litruv" "thumbnail": "img/default-thumbnail.png",
"site_name": "DocsHub"
}, },
"documents": [ "documents": [
{ {
"title": "Welcome", "title": "Home",
"path": "docs/index.md", "path": "docs/index.md",
"slug": "welcome" "slug": "home"
}, },
{ {
"title": "Unreal Engine", "title": "Category One",
"type": "folder", "type": "folder",
"path": "docs/category-one.md",
"color": "#2196f3", "color": "#2196f3",
"path": "docs/unreal-engine.md",
"slug": "unreal-engine",
"items": [ "items": [
{ {
"title": "DeepImpact", "title": "Feature A",
"path": "docs/DeepImpact.md", "path": "docs/feature-a.md",
"slug": "deep-impact" "slug": "feature-a"
}, },
{ {
"title": "WIP: Objective Marker System", "title": "Feature B",
"path": "docs/objective-marker-system.md", "path": "docs/feature-b.md",
"slug": "objective-markers", "slug": "feature-b",
"thumbnail": "images/docThumb.png" "thumbnail": "images/docThumb.png"
} }
] ]
} }
], ],
"author": { "author": {
"name": "Litruv", "name": "John Doe",
"role": "Dev/Tech Artist @MatesMedia", "role": "Software Engineer",
"socials": [ "socials": [
{ {
"icon": "fab fa-github", "icon": "fab fa-github",
"url": "https://github.com/Litruv", "url": "https://github.com/johndoe",
"title": "GitHub - Litruv" "title": "GitHub - JohnDoe"
}, },
{ {
"icon": "fab fa-youtube", "icon": "fab fa-youtube",
"url": "https://www.youtube.com/c/Litruv", "url": "https://youtube.com/c/JohnDoe",
"title": "YouTube - Litruv" "title": "YouTube - JohnDoe"
}, },
{ {
"icon": "fab fa-discord", "icon": "fab fa-discord",
"url": "https://discordapp.com/users/220772082055774210", "url": "https://discordapp.com/users/1234567890",
"title": "Discord - @Litruv" "title": "Discord - @JohnDoe"
}, },
{ {
"icon": "fa-brands fa-bluesky", "icon": "fa-brands fa-bluesky",
"url": "https://bsky.app/profile/lit.mates.dev", "url": "https://bsky.app/profile/john.doe.dev",
"title": "Bluesky - lit.mates.dev" "title": "Bluesky - john.doe.dev"
} }
] ]
} }