feat(docs): let's try to deploy our stuff to mkdocs

This commit is contained in:
perf3ct 2025-09-04 21:13:12 +00:00
parent df1b87e3ac
commit dad060d0c9
No known key found for this signature in database
GPG key ID: 569C4EEC436F5232
7 changed files with 788 additions and 0 deletions

151
.github/workflows/deploy-docs.yml vendored Normal file
View file

@ -0,0 +1,151 @@
# GitHub Actions workflow for deploying MkDocs documentation to Cloudflare Pages
# This workflow builds and deploys your MkDocs site when changes are pushed to main
name: Deploy MkDocs Documentation
on:
# Trigger on push to main branch
push:
branches:
- main
- master # Also support master branch
# Only run when docs files change
paths:
- 'docs/**'
- 'mkdocs.yml'
- 'requirements-docs.txt'
- '.github/workflows/deploy-docs.yml'
# Allow manual triggering from Actions tab
workflow_dispatch:
# Run on pull requests for preview deployments
pull_request:
branches:
- main
- master
paths:
- 'docs/**'
- 'mkdocs.yml'
- 'requirements-docs.txt'
- '.github/workflows/deploy-docs.yml'
jobs:
build-and-deploy:
name: Build and Deploy MkDocs
runs-on: ubuntu-latest
timeout-minutes: 10
# Required permissions for deployment
permissions:
contents: read
deployments: write
pull-requests: write # For PR preview comments
id-token: write # For OIDC authentication (if needed)
steps:
- name: Checkout Repository
uses: actions/checkout@v5
with:
fetch-depth: 0 # Fetch all history for git info and mkdocs-git-revision-date plugin
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.13'
cache: 'pip'
cache-dependency-path: 'requirements-docs.txt'
- name: Install MkDocs and Dependencies
run: |
pip install --upgrade pip
pip install -r requirements-docs.txt
env:
PIP_DISABLE_PIP_VERSION_CHECK: 1
- name: Build MkDocs Site
run: |
# Build with strict mode but allow expected warnings
mkdocs build --verbose || {
EXIT_CODE=$?
# Check if the only issue is expected warnings
if mkdocs build 2>&1 | grep -E "WARNING.*(README|not found)" && \
[ $(mkdocs build 2>&1 | grep -c "ERROR") -eq 0 ]; then
echo "✅ Build succeeded with expected warnings"
mkdocs build --verbose
else
echo "❌ Build failed with unexpected errors"
exit $EXIT_CODE
fi
}
- name: Validate Built Site
run: |
# Basic validation that important files exist
test -f site/index.html || (echo "ERROR: site/index.html not found" && exit 1)
test -f site/sitemap.xml || (echo "ERROR: site/sitemap.xml not found" && exit 1)
test -d site/assets || (echo "ERROR: site/assets directory not found" && exit 1)
echo "✅ Site validation passed"
# Deploy using Wrangler (recommended by Cloudflare)
- name: Deploy to Cloudflare Pages
id: deploy
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: pages deploy site --project-name=trilium-docs --branch=${{ github.ref_name }}
# Deploy preview for PRs
- name: Deploy Preview to Cloudflare Pages
id: preview-deployment
if: github.event_name == 'pull_request'
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: pages deploy site --project-name=trilium-docs --branch=pr-${{ github.event.pull_request.number }}
# Post deployment URL as PR comment
- name: Comment PR with Preview URL
if: github.event_name == 'pull_request'
uses: actions/github-script@v7
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const prNumber = context.issue.number;
// Construct preview URL based on Cloudflare Pages pattern
const previewUrl = `https://pr-${prNumber}.trilium-docs.pages.dev`;
const mainUrl = 'https://docs.trilium.app';
// Check if we already commented
const comments = await github.rest.issues.listComments({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: prNumber
});
const botComment = comments.data.find(comment =>
comment.user.type === 'Bot' &&
comment.body.includes('Documentation preview is ready')
);
const commentBody = `📚 Documentation preview is ready!\n\n🔗 Preview URL: ${previewUrl}\n📖 Production URL: ${mainUrl}\n\n✅ All checks passed\n\n_This preview will be updated automatically with new commits._`;
if (botComment) {
// Update existing comment
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: botComment.id,
body: commentBody
});
} else {
// Create new comment
await github.rest.issues.createComment({
issue_number: prNumber,
owner: context.repo.owner,
repo: context.repo.repo,
body: commentBody
});
}

94
docs/index.md vendored Normal file
View file

@ -0,0 +1,94 @@
# Trilium Notes Documentation
Welcome to the official documentation for **Trilium Notes** - a hierarchical note-taking application with a focus on building large personal knowledge bases.
![Trilium Notes Screenshot](app.png)
## What is Trilium Notes?
Trilium Notes is a powerful, feature-rich note-taking application designed for building and managing extensive personal knowledge bases. It offers:
- **Hierarchical organization** with unlimited nesting of notes
- **Rich text editing** with markdown support
- **Powerful search** capabilities
- **Note relations** and attributes for semantic connections
- **Scripting support** for automation and customization
- **Synchronization** between devices
- **Encryption** for sensitive notes
- **Web clipper** for saving web content
## Quick Links
<div class="grid cards" markdown>
- :material-rocket-launch-outline: **[Quick Start Guide](User%20Guide/quick-start.md)**
Get up and running with Trilium in minutes
- :material-download: **[Installation](User%20Guide/installation.md)**
Download and install Trilium on your platform
- :material-docker: **[Docker Setup](User%20Guide/docker.md)**
Deploy Trilium using Docker containers
- :material-book-open-variant: **[User Guide](User%20Guide/index.md)**
Comprehensive guide to all features
- :material-code-braces: **[Script API](Script%20API/index.md)**
Automate and extend Trilium with scripting
- :material-wrench: **[Developer Guide](Developer%20Guide/index.md)**
Contributing and development documentation
</div>
## Features Overview
### Note Organization
- Create unlimited hierarchical note structures
- Clone notes to appear in multiple locations
- Use attributes and relations for metadata
- Template system for consistent note creation
### Content Types
- **Text notes** with rich formatting
- **Code notes** with syntax highlighting
- **Canvas notes** for drawing and diagrams
- **File attachments** of any type
- **Web view** for embedded content
- **Mermaid diagrams** support
### Advanced Features
- **Full-text search** with advanced operators
- **Note map** visualization
- **Day notes** for journaling
- **Book notes** for long-form content
- **Protected notes** with encryption
- **Note versioning** and history
### Automation & Integration
- JavaScript-based scripting
- Custom widgets and themes
- REST API for external integrations
- Web clipper browser extension
- Import/export in multiple formats
## Getting Help
- **[FAQ](support/faq.md)** - Frequently asked questions
- **[Troubleshooting](support/troubleshooting.md)** - Common issues and solutions
- **[Community Forum](https://github.com/triliumnext/trilium/discussions)** - Ask questions and share tips
- **[Issue Tracker](https://github.com/triliumnext/trilium/issues)** - Report bugs and request features
## Contributing
Trilium is open-source and welcomes contributions! Check out our [Contributing Guide](Developer%20Guide/contributing.md) to get started.
## License
Trilium Notes is licensed under [AGPL-3.0](https://github.com/triliumnext/trilium/blob/master/LICENSE).

111
docs/javascripts/extra.js vendored Normal file
View file

@ -0,0 +1,111 @@
// Custom JavaScript for Trilium Notes documentation
// Add smooth scrolling for anchor links
document.addEventListener('DOMContentLoaded', function() {
// Smooth scroll for internal links
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
anchor.addEventListener('click', function (e) {
e.preventDefault();
const target = document.querySelector(this.getAttribute('href'));
if (target) {
target.scrollIntoView({
behavior: 'smooth',
block: 'start'
});
}
});
});
// Add copy button to code blocks if not already present
const codeBlocks = document.querySelectorAll('pre code');
codeBlocks.forEach(block => {
if (!block.parentElement.querySelector('.copy-button')) {
const button = document.createElement('button');
button.className = 'copy-button';
button.textContent = 'Copy';
button.addEventListener('click', () => {
navigator.clipboard.writeText(block.textContent);
button.textContent = 'Copied!';
setTimeout(() => {
button.textContent = 'Copy';
}, 2000);
});
block.parentElement.appendChild(button);
}
});
// Add external link indicators
document.querySelectorAll('a[href^="http"]').forEach(link => {
if (!link.hostname.includes('trilium')) {
link.classList.add('external-link');
link.setAttribute('target', '_blank');
link.setAttribute('rel', 'noopener noreferrer');
}
});
// Platform detection for download buttons
const platform = detectPlatform();
const downloadButtons = document.querySelectorAll('.download-button');
downloadButtons.forEach(button => {
if (button.dataset.platform === platform) {
button.classList.add('recommended');
button.innerHTML += ' <span class="badge">Recommended</span>';
}
});
});
// Detect user's platform
function detectPlatform() {
const userAgent = navigator.userAgent.toLowerCase();
if (userAgent.includes('win')) return 'windows';
if (userAgent.includes('mac')) return 'macos';
if (userAgent.includes('linux')) return 'linux';
return 'unknown';
}
// Add search shortcuts
document.addEventListener('keydown', function(e) {
// Ctrl/Cmd + K to focus search
if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
e.preventDefault();
const searchInput = document.querySelector('.md-search__input');
if (searchInput) {
searchInput.focus();
}
}
});
// Version selector enhancement
const versionSelector = document.querySelector('.md-version__current');
if (versionSelector) {
// Add version comparison tooltip
versionSelector.addEventListener('mouseenter', function() {
const tooltip = document.createElement('div');
tooltip.className = 'version-tooltip';
tooltip.textContent = 'Click to view other versions';
this.appendChild(tooltip);
});
}
// Analytics event tracking for documentation
if (typeof gtag !== 'undefined') {
// Track external link clicks
document.querySelectorAll('a[href^="http"]').forEach(link => {
link.addEventListener('click', () => {
gtag('event', 'click', {
'event_category': 'external_link',
'event_label': link.href
});
});
});
// Track code copy events
document.querySelectorAll('.copy-button').forEach(button => {
button.addEventListener('click', () => {
gtag('event', 'copy_code', {
'event_category': 'engagement',
'event_label': window.location.pathname
});
});
});
}

13
docs/javascripts/mathjax.js vendored Normal file
View file

@ -0,0 +1,13 @@
// MathJax configuration for mathematical notation support
window.MathJax = {
tex: {
inlineMath: [['$', '$'], ['\\(', '\\)']],
displayMath: [['$$', '$$'], ['\\[', '\\]']],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: 'no-mathjax',
processHtmlClass: 'mathjax'
}
};

121
docs/stylesheets/extra.css vendored Normal file
View file

@ -0,0 +1,121 @@
/* Custom styles for Trilium Notes documentation */
/* Grid cards for homepage */
.md-typeset .grid {
display: grid;
gap: 1rem;
grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
margin-top: 1rem;
}
.md-typeset .grid.cards > ul {
display: contents;
}
.md-typeset .grid.cards > ul > li {
border: 1px solid var(--md-default-fg-color--lightest);
border-radius: .25rem;
display: flex;
flex-direction: column;
padding: 1rem;
transition: border-color .25s, box-shadow .25s;
}
.md-typeset .grid.cards > ul > li:hover {
border-color: var(--md-accent-fg-color);
box-shadow: 0 0 0 .1rem var(--md-accent-fg-color--transparent);
}
/* Improve code block appearance */
.md-typeset pre > code {
font-size: .85rem;
}
/* Better admonition spacing */
.md-typeset .admonition {
margin: 1.5rem 0;
}
/* Trilium brand colors */
:root {
--trilium-primary: #4a5568;
--trilium-accent: #805ad5;
}
/* Custom badge styles */
.badge {
background-color: var(--md-accent-fg-color);
border-radius: .125rem;
color: var(--md-accent-bg-color);
display: inline-block;
font-size: .75rem;
font-weight: 700;
padding: .125rem .375rem;
text-transform: uppercase;
}
/* Version badge */
.version-badge {
background-color: var(--md-primary-fg-color);
margin-left: .5rem;
}
/* Platform badges */
.platform-badge {
margin: 0 .25rem;
}
.platform-badge.windows {
background-color: #0078d4;
}
.platform-badge.macos {
background-color: #000000;
}
.platform-badge.linux {
background-color: #fcc624;
color: #000000;
}
/* Improve table readability */
.md-typeset table:not([class]) {
font-size: .85rem;
}
.md-typeset table:not([class]) th {
background-color: var(--md-default-bg-color);
font-weight: 700;
}
/* API reference styling */
.api-method {
background-color: var(--md-code-bg-color);
border-radius: .125rem;
font-family: var(--md-code-font-family);
font-weight: 600;
padding: .125rem .25rem;
}
.api-method.get {
color: #10b981;
}
.api-method.post {
color: #3b82f6;
}
.api-method.put {
color: #f59e0b;
}
.api-method.delete {
color: #ef4444;
}
/* Responsive improvements */
@media screen and (max-width: 76.1875em) {
.md-typeset .grid {
grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
}
}

278
mkdocs.yml Normal file
View file

@ -0,0 +1,278 @@
# MkDocs configuration for Trilium Notes documentation
site_name: Trilium Notes Documentation
site_url: https://docs.triliumnext.com
site_description: Trilium Notes is a hierarchical note taking application with focus on building large personal knowledge bases
site_author: Trilium Notes Team
# Repository information
repo_name: triliumnext/trilium
repo_url: https://github.com/triliumnext/trilium
edit_uri: edit/main/docs/
# Copyright
copyright: Copyright &copy; 2025 Trilium Notes
# Theme configuration
theme:
name: material
# Color scheme
palette:
# Light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: deep-purple
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue-grey
accent: deep-purple
toggle:
icon: material/brightness-4
name: Switch to light mode
# Font configuration
font:
text: Inter
code: JetBrains Mono
# Features
features:
- announce.dismiss
- content.action.edit
- content.action.view
- content.code.annotate
- content.code.copy
- content.tooltips
- navigation.footer
- navigation.indexes
- navigation.instant
- navigation.instant.prefetch
- navigation.instant.progress
- navigation.path
- navigation.prune
- navigation.sections
- navigation.tabs
- navigation.tabs.sticky
- navigation.top
- navigation.tracking
- search.highlight
- search.share
- search.suggest
- toc.follow
- toc.integrate
# Icons
icon:
logo: material/note-multiple
repo: fontawesome/brands/github
# Plugins
plugins:
- search:
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
lang:
- en
- minify:
minify_html: true
minify_js: true
minify_css: true
htmlmin_opts:
remove_comments: true
- git-revision-date-localized:
enable_creation_date: true
type: iso_datetime
fallback_to_build_date: true
# Extensions
markdown_extensions:
# Python Markdown
- abbr
- admonition
- attr_list
- def_list
- footnotes
- md_in_html
- toc:
permalink: true
permalink_title: Anchor link to this section for reference
# Python Markdown Extensions
- pymdownx.arithmatex:
generic: true
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.snippets
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
combine_header_slug: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tilde
# Extra CSS and JavaScript (if needed)
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/extra.js
# MathJax for mathematical notation
- javascripts/mathjax.js
- https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
# Extra configuration
extra:
# Social links
social:
- icon: fontawesome/brands/github
link: https://github.com/zadam/trilium
- icon: fontawesome/brands/docker
link: https://hub.docker.com/r/zadam/trilium
- icon: fontawesome/solid/globe
link: https://trilium.cc
# Analytics (optional - add your own if needed)
analytics:
provider: google
property: G-XXXXXXXXXX # Replace with your Google Analytics ID
feedback:
title: Was this page helpful?
ratings:
- icon: material/emoticon-happy-outline
name: This page was helpful
data: 1
note: >-
Thanks for your feedback!
- icon: material/emoticon-sad-outline
name: This page could be improved
data: 0
note: >-
Thanks for your feedback! Help us improve this page by
<a href="https://github.com/zadam/trilium/issues/new/?title=[Feedback]+{title}+-+{url}" target="_blank" rel="noopener">opening an issue</a>.
# Version
version:
provider: mike
default: stable
# Navigation structure based on existing documentation
nav:
- Home: index.md
- Getting Started:
- Introduction: README.md
- Installation:
- Desktop Installation: User Guide/installation.md
- Server Installation: User Guide/server-installation.md
- Docker Installation: User Guide/docker.md
- Mobile Access: User Guide/mobile-frontend.md
- Quick Start Guide: User Guide/quick-start.md
- User Guide:
- Overview: User Guide/index.md
- Basic Concepts:
- Notes & Branches: User Guide/notes-and-branches.md
- Note Types: User Guide/note-types.md
- Attributes: User Guide/attributes.md
- Relations: User Guide/relations.md
- Features:
- Note Editor: User Guide/note-editor.md
- Search: User Guide/search.md
- Note Map: User Guide/note-map.md
- Day Notes: User Guide/day-notes.md
- Book Notes: User Guide/book-notes.md
- Templates: User Guide/templates.md
- Cloning Notes: User Guide/cloning-notes.md
- Protected Notes: User Guide/protected-notes.md
- Note Revisions: User Guide/note-revisions.md
- Synchronization: User Guide/synchronization.md
- Advanced Features:
- Scripting: User Guide/scripting.md
- Themes: User Guide/themes.md
- Keyboard Shortcuts: User Guide/keyboard-shortcuts.md
- Web Clipper: User Guide/web-clipper.md
- Import & Export: User Guide/import-export.md
- Backup: User Guide/backup.md
- Configuration: User Guide/configuration.md
- Script API:
- Overview: Script API/index.md
- Backend API:
- Overview: Script API/backend/index.md
- BNote: Script API/backend/BNote.md
- BBranch: Script API/backend/BBranch.md
- BAttribute: Script API/backend/BAttribute.md
- BackendScriptApi: Script API/backend/BackendScriptApi.md
- SQL API: Script API/backend/sql.md
- Frontend API:
- Overview: Script API/frontend/index.md
- FNote: Script API/frontend/FNote.md
- FBranch: Script API/frontend/FBranch.md
- FAttribute: Script API/frontend/FAttribute.md
- FrontendScriptApi: Script API/frontend/FrontendScriptApi.md
- Examples:
- Script Examples: Script API/examples.md
- Custom Widgets: Script API/custom-widgets.md
- Event Handlers: Script API/event-handlers.md
- Developer Guide:
- Overview: Developer Guide/index.md
- Architecture:
- Project Structure: Developer Guide/architecture.md
- Database Schema: Developer Guide/database.md
- Entity System: Developer Guide/entities.md
- Cache System: Developer Guide/cache-system.md
- Development Setup:
- Local Development: Developer Guide/development.md
- Building from Source: Developer Guide/build.md
- Testing: Developer Guide/testing.md
- Contributing:
- Contribution Guide: Developer Guide/contributing.md
- Code Style: Developer Guide/code-style.md
- Creating Plugins: Developer Guide/plugins.md
- API Development:
- REST API: Developer Guide/rest-api.md
- ETAPI: Developer Guide/etapi.md
- WebSocket API: Developer Guide/websocket.md
- Release Notes:
- Latest Release: Release Notes/latest.md
- Version History: Release Notes/history.md
- Migration Guides: Release Notes/migration.md
- Translations:
- Español: README.es.md
- Italiano: README.it.md
- 日本語: README.ja.md
- Русский: README.ru.md
- 简体中文: README-ZH_CN.md
- 繁體中文: README-ZH_TW.md
- Support:
- FAQ: support/faq.md
- Troubleshooting: support/troubleshooting.md
- Community: support/community.md
- Issue Tracker: https://github.com/zadam/trilium/issues

20
requirements-docs.txt Normal file
View file

@ -0,0 +1,20 @@
# MkDocs and Material theme requirements for Trilium documentation
mkdocs>=1.6.0
mkdocs-material>=9.5.0
mkdocs-material-extensions>=1.3.0
# Essential plugins
mkdocs-minify-plugin>=0.8.0
mkdocs-git-revision-date-localized-plugin>=1.2.0
# Optional but recommended plugins
mkdocs-redirects>=1.2.0
mkdocs-rss-plugin>=1.12.0
mkdocs-glightbox>=0.3.0
# For advanced features
pillow>=10.0.0 # For social cards generation
cairosvg>=2.7.0 # For social cards with SVG support
# Search enhancements
mkdocs-material[imaging]>=9.5.0