diff --git a/README.md b/README.md index 915c56d..6090117 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,20 @@ A robust, modern documentation viewer built for rendering Markdown files with ad ## Quick Start ### Development Setup -[Fork this Repo](https://github.com/litruv/Docs-Viewer/fork) + +[Fork this Repo](https://github.com/example/Docs-Viewer/fork) #### Updating + ##### From GitHub + On your own repo, + 1. Click Sync fork 2. Update branch + ##### From CLI + ```sh git fetch upstream git merge upstream/master @@ -34,31 +40,31 @@ Deploy anywhere that serves static files. For local development: VSCode: [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 npx live-server ``` +#### Cloudflare Pages -#### 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. +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, eg. `https://lit.ruv.wtf/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. +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. ## Project Structure @@ -72,13 +78,12 @@ For improved SEO and social sharing, you can use a Cloudflare Worker to dynamica └── 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`: ```json { - "title": "My Documentation Site", "defaultPage": "welcome", "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 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. -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 -| Option | Type | Description | -|---------------|--------|----------------------------------------------------------| -| `title` | string | Title of your documentation site | -| `defaultPage` | string | Slug of the page to show when no page is specified | -| `documents` | array | Array of document or folder entries (see below) | +| Option | Type | Description | | +| ------------- | ------ | -------------------------------------------------- | - | +| `defaultPage` | string | Slug of the page to show when no page is specified | | +| `documents` | array | Array of document or folder entries (see below) | | ### Folder Organization @@ -118,23 +116,18 @@ Folders can contain nested documents or subfolders. Mark a folder by setting `"t ```json { - "title": "My Documentation Site", - "defaultPage": "welcome", - "documents": [ + "title": "Core Concepts", + "type": "folder", + "path": "docs/core-concepts/index.md", + "slug": "core-concepts", + "defaultOpen": true, + "icon": "fa-solid fa-book", + "color": "#01beef + "items": [ { - "title": "Core Concepts", - "type": "folder", - "defaultOpen": true, - "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" - } - ] + "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 -| Option | Type | Description | -|-----------------|----------|----------------------------------------------------| -| `type` | string | Set to `"folder"` for a directory node | -| `title` | string | Display name of the folder | -| `path` | string? | Optional content file path | -| `slug` | string | URL-friendly identifier; required if `path` exists| -| `items` | array | Nested documents or folders | -| `defaultOpen` | boolean? | Automatically expand this folder in the sidebar | -| `icon` | string? | Custom Font Awesome classes | +| Option | Type | Description | +| ------------- | -------- | -------------------------------------------------- | +| `title` | string | Display name of the folder | +| `type` | string | Set to `"folder"` for a directory node | +| `path` | string? | Optional content file path | +| `slug` | string | URL-friendly identifier; required if `path` exists | +| `defaultOpen` | boolean? | Automatically expand this folder in the sidebar | +| `icon` | string? | Custom Font Awesome classes | +| `items` | array | Nested documents or folders | ## Metadata Configuration +> To be used with the cloudflare-worker.js + You can include a "metadata" object in `index.json` to provide: + - Site-wide title and short description - Thumbnail for social sharing - Display name for your site ```json "metadata": { - "title": "Litruv / Documentation", - "description": "Documentation for Litruv's plugins", + "site_name": "MyDocs" + "description": "Documentation for my project", "thumbnail": "img/og-image.png", - "site_name": "Litruv" } ``` #### Metadata Configuration Options -| Option | Type | Description | -|---------------|--------|----------------------------------------------------------| -| `title` | string | Title of your documentation site | -| `description` | string | Description of your documentation site | -| `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 +| Option | Type | Description | +| ------------- | ------ | ------------------------------------------- | +| `site_name` | string | Display name for your site | +| `description` | string | Description of your documentation site | +| `thumbnail` | string | URL to a thumbnail image for social sharing | ## License @@ -216,3 +178,4 @@ Released under the MIT License. See [LICENSE](LICENSE) for details. ## Contributing Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details. + diff --git a/example.index.json b/example.index.json index b66accf..f91a773 100644 --- a/example.index.json +++ b/example.index.json @@ -1,60 +1,61 @@ { - "defaultPage": "welcome", + "defaultPage": "home", + "customCSS": "custom/theme.css", "metadata": { - "description": "Documentation for Litruv's plugins", - "thumbnail": "img/og-image.png", - "site_name": "Litruv" + "title": "Project Documentation", + "description": "Comprehensive documentation for various projects.", + "thumbnail": "img/default-thumbnail.png", + "site_name": "DocsHub" }, "documents": [ { - "title": "Welcome", + "title": "Home", "path": "docs/index.md", - "slug": "welcome" + "slug": "home" }, { - "title": "Unreal Engine", + "title": "Category One", "type": "folder", + "path": "docs/category-one.md", "color": "#2196f3", - "path": "docs/unreal-engine.md", - "slug": "unreal-engine", "items": [ { - "title": "DeepImpact", - "path": "docs/DeepImpact.md", - "slug": "deep-impact" + "title": "Feature A", + "path": "docs/feature-a.md", + "slug": "feature-a" }, { - "title": "WIP: Objective Marker System", - "path": "docs/objective-marker-system.md", - "slug": "objective-markers", + "title": "Feature B", + "path": "docs/feature-b.md", + "slug": "feature-b", "thumbnail": "images/docThumb.png" } ] } ], "author": { - "name": "Litruv", - "role": "Dev/Tech Artist @MatesMedia", + "name": "John Doe", + "role": "Software Engineer", "socials": [ { "icon": "fab fa-github", - "url": "https://github.com/Litruv", - "title": "GitHub - Litruv" + "url": "https://github.com/johndoe", + "title": "GitHub - JohnDoe" }, { "icon": "fab fa-youtube", - "url": "https://www.youtube.com/c/Litruv", - "title": "YouTube - Litruv" + "url": "https://youtube.com/c/JohnDoe", + "title": "YouTube - JohnDoe" }, { "icon": "fab fa-discord", - "url": "https://discordapp.com/users/220772082055774210", - "title": "Discord - @Litruv" + "url": "https://discordapp.com/users/1234567890", + "title": "Discord - @JohnDoe" }, { "icon": "fa-brands fa-bluesky", - "url": "https://bsky.app/profile/lit.mates.dev", - "title": "Bluesky - lit.mates.dev" + "url": "https://bsky.app/profile/john.doe.dev", + "title": "Bluesky - john.doe.dev" } ] }