Example Article

Polar Docs: Comprehensive Guide to Building and Using the Documentation Platform 🔗

Welcome to a detailed, example article demonstrating how to author rich documentation for Polar Docs. This article shows recommended structure, best practices, and many markdown features — including custom blocks like :::note and :::callout which the Polar parser recognizes.

- Estimated read time: 12–18 minutes - Tags: docs, polar, tutorial, example, markdown - Keywords: documentation, admin, theme, search, custom blocks

# clone the repo (example)
git clone https://github.com/your-org/polar-docs.git
cd polar-docs
# ensure data directory is writable
chown -R www-data:www-data data
chmod -R 775 data
# visit https://yourhost/admin.php to continue setup

Note:This article is intentionally extensive to showcase headings, code samples, tables, images, callouts, checklists, and custom admonitions. Use it as a template when creating new docs. ::: --- ## Table of Contents 1. Introduction 2. Quick Start — Installation & Setup 3. Project Structure 4. Writing Articles: Style & Patterns 5. Advanced Markdown Features 6. Custom Blocks and Callouts 7. Search, SEO & Metadata 8. The Admin Panel: Managing Articles 9. Theming and Appearance 10. FAQ & Troubleshooting 11. Change Log Example 12. Appendix: Full Example Snippets --- ## Introduction Polar Docs is a lightweight, filesystem-backed documentation engine designed for quick setup, modern UI, and flexible content authored in Markdown. This example article demonstrates: - How to organize content and categories - Using Polar's custom markdown elements - Creating shareable section anchors with share menus - Managing content via the admin panel If you're new to Polar Docs, read the Quick Start below. If you're already set up, skip ahead to "Writing Articles". --- ## Quick Start — Installation & Setup Follow these steps to get a working site: 1. Place the Polar project in your web server document root (Apache, Nginx + PHP-FPM). 2. Ensure PHP 7.4+ is available. 3. Make the data/ directory writable by the web server (this is where JSON and markdown files live). 4. Open /admin.php in your browser and set an admin password. 5. Create your first category and article in the admin UI. Example commands (Unix-like environment):

If hosting on shared hosting, enable HTTPS and restrict access to admin.php by IP if possible. For production, integrate stronger authentication (OAuth, SSO) and consider moving metadata to a DB. :::

Project Structure 🔗

A typical Polar install looks like:

- index.php — public site + API endpoints - admin.php — admin panel (single-file frontend+backend) - assets/ - app.js - styles.css - data/ - config.json - categories.json - articles.json - themes.json - articles/*.md

Recommended layout for your docs repository:

docs/
├─ getting-started/
│  ├─ installation.md
│  └─ overview.md
├─ guides/
│  ├─ authoring.md
│  └─ advanced.md
└─ reference/
   └─ api.md

When creating articles in the admin, Polar stores each article as an .md file in data/articles/ and keeps a JSON index entry with UUIDs for stable URLs.

Writing Articles: Style & Patterns 🔗

Good documentation is consistent and scannable. Use these guidelines:

- Write descriptive headings (H1 for article title, H2/H3 for sections). - Keep intro paragraphs short — most readers will skim. - Use bullet lists for steps and numbered lists for sequences. - Add a short excerpt (1–2 sentences) for sidebar previews. - Tag articles with keywords to improve search relevance.

Example section header usage:

## Install the CLI
Explain what it does and provide a one-line summary.

### Linux
Provide distro-specific commands.

### macOS
Brew instructions go here.

Advanced Markdown Features 🔗

Polar's parser supports standard markdown plus several enhancements:

- Code fences with language hints (``php, `bash, `javascript) - Images: alt text - Tables (basic) - Inline code:git clone ...- Custom blocks::::note, :::callout, and raw :::` sections

Example table:

| Feature | Supported | Notes | |-------------------|:---------:|-------| | Code fences | ✅ | with syntax highlighting class | | Custom blocks | ✅ | :::note and :::callout | | Footnotes | ⚠️ | not yet — may be added later |

Code Example — API Call (JavaScript) 🔗

fetch('/index.php?action=search&q=documentation')
  .then(r => r.json())
  .then(results => console.log('found', results));

Custom Blocks and Callouts 🔗

Polar recognizes special blocks that start and end with :::. Use these to draw attention.

Note block example:

Note:This is a short note. Use :::note for helpful clarifications, background details, or links to related articles. ::: Callout example (useful for warnings or high-priority info):

Warning: If you change an article's slug manually, the old URL will break unless you also update the UUID mapping in articles.json. :::

Generic custom block:

::: You can use a raw ::: block for custom styling. The parser will render it as a neutral panel. :::

Search, SEO & Metadata 🔗

Polar's search is keyword-based and scans both article metadata and the markdown text. To improve discoverability:

- Provide a helpful excerpt in article metadata. - Add tags for common terms (comma-separated in the admin UI). - Use descriptive filenames and slugs — they appear in sidebar and breadcrumbs.

Example metadata snippet (conceptual):

{
  "title": "Installation Guide",
  "slug": "installation-guide",
  "excerpt": "Install Polar quickly on Linux, macOS and Windows.",
  "tags": ["install", "setup", "linux", "macos"]
}

SEO tips: - Use meaningful headings (H1/H2). - Use descriptive link text (avoid "click here"). - Provide social meta tags in a customized index.php if you want share previews.

The Admin Panel: Managing Articles 🔗

The admin UI allows:

- Creating categories and subcategories - Creating, editing, deleting articles (files in data/articles/) - Setting the site theme - Viewing article UUIDs for stable URLs

Important admin operations: - Changing the admin password: Go to /admin.php - Creating an article: Provide title, category, excerpt, tags, and markdown content - Deleting an article: Admin UI will remove both the JSON entry and the corresponding .md file

--bg: #0f172a;
--panel: #0b1220;
--muted: #9aa4b2;
--accent: #06b6d4;
--text: #e6eef8;

<?php
// Simple helper to generate article links
function article_url($meta) {
  return "/realms/document/polar/" . implode('/', $meta['category_path']) . "/" . $meta['slug'] . "/" . $meta['uuid'];
}
?>

// Copy current section URL (used by the share menu)
function copySectionUrl(id) {
  const url = location.origin + location.pathname + '#' + id;
  navigator.clipboard.writeText(url).then(() => {
    alert('Copied to clipboard');
  });
}

# Linux / macOS
curl -sSL https://example.com/polar-cli/install.sh | bash

# Verify
polar --version