DOCSEARCHbyAlgolia
Submit Docs

Frappe Wiki Documentation

repository·develop·Indexed 19 days ago

https://github.com/frappe/wiki

An open-source documentation and knowledge base tool built on the Frappe Framework. It features Markdown authoring, controlled update workflows with review and approval, revision history, and a Vue-based Single Page Application (SPA) frontend. The system utilizes Ace Editor for content editing and RedisSearch for indexing, supporting advanced Tiptap extensions for callout blocks and secure iframe embeds from allowlisted providers.

Tokens
53.6K
Snippets
114
Records
242
Agent score
64%

What's inside Frappe Wiki

  1. Overview of Frappe Wiki

    develop

    Frappe Wiki is an open-source documentation tool built on the Frappe Framework. It is designed for managing dynamic, text-heavy content such as knowledge bases and user manuals.

    Key capabilities include:

    • Markdown Authoring: Write and format content using Markdown syntax.
    • Controlled Updates: Implement workflows for reviewing and approving edits before they are published.
    • Revision History: Maintain a history of changes to pages.
    • Attachments: Attach files directly to wiki pages.
    • Navigation: Automatically generated Tables of Contents.
    • Extensibility: Support for custom scripts via Wiki Settings.

    Technically, it utilizes the Ace Editor for content editing and RedisSearch for powerful search and indexing capabilities.

  2. Mobile-Friendly Wiki Implementation Overview

    develop

    The Wiki Single Page Application (SPA) has been updated to be fully usable on mobile devices (viewports < 768px). The implementation follows patterns established in Frappe CRM, utilizing a mobile-first approach with Vue 3, frappe-ui, and Tailwind CSS.

    Key mobile features include:

    • Navigation: Global navigation and document trees are moved to off-canvas drawers (sidebars) toggled by a hamburger menu.
    • List Views: Spaces and Change Requests use horizontal scrolling within frappe-ui ListView components rather than converting to cards.
    • Editor: The editor supports core editing (formatting, images, saving) with a horizontally-scrollable top toolbar and touch-optimized targets (minimum 44x44px).
    • Layout: The application swaps between MobileLayout and DesktopLayout at the root level based on screen width.

  3. Understand the Frappe Wiki architecture

    develop

    Frappe Wiki is split into two main components:

    1. Backend: A Frappe app located in the wiki/ directory, written in Python. It manages the data schema, business logic, and public page rendering.
    2. Frontend: A Single Page Application (SPA) located in the frontend/ directory, built with Vue and frappe-ui. The compiled assets are served from /assets/wiki/frontend.

    The system uses a combination of server-side rendering for published documents and a client-side SPA for the interactive wiki application.

  4. Implementation details for Mermaid block integration

    develop

    For developers extending or maintaining the Wiki, the Mermaid implementation follows these architectural patterns:

    Editor Integration (TipTap/Vue)

    • Node Type: A new node mermaid-block.js and MermaidBlockView.vue are used.
    • Registration: The extension is registered in WikiEditor.vue.
    • Access: Authors can insert blocks via the toolbar or the /mermaid slash command.
    • Precedence: The Mermaid tokenizer must take precedence over the default TipTap fenced-code-block tokenizer when lang === 'mermaid'.

    Public Reader Integration (Jinja/Python/Alpine.js)

    • Interception Point: The fence render rule in wiki/markdown.py::_build_markdown (around line 406) is used to intercept lang == "mermaid".
    • Output: Instead of a <pre><code> block, the renderer emits a hydration container. The diagram source is placed in a data attribute or a <template> tag (HTML-escaped) to prevent execution.
    • Hydration: Client-side JS in wiki/public/js/ handles the lazy loading and rendering of the SVG.

  5. Understand the `/wiki` vs `/wiki-app` route distinction

    develop

    In Frappe Wiki v3, the application routes have been split to prevent conflicts between the editor and user-created content:

    • /wiki-app: The authenticated editor Single Page Application (SPA). All editing interfaces, space management, and editor entry points now reside here.
    • /wiki: Reserved for public content. Users can now create their own Wiki Spaces using the /wiki route (e.g., /wiki/my-space) without the application's editor SPA intercepting the request.

    Note: This is a breaking change. Existing bookmarks to /wiki/... for editing purposes will no longer work and must be updated to /wiki-app/....

  6. Route Sanitization Rules

    develop

    All client-supplied routes are processed through a sanitize_route helper to ensure they follow the application's slugging standards. The sanitization process involves:

    • Splitting the route by / segments.
    • Running each segment through the standard slug rule (equivalent to cleanup_page_name(title).replace("_", "-")).
    • Dropping empty segments.
    • Rejoining the segments with /.

    This ensures that even if a user manually types a messy URL, it is converted into a valid, clean slug format before being saved.

  8. How the meta image generation works under the hood

    develop

    The meta image generation avoids external microservices by using a native framework utility.

    Core Mechanism:

    • Renderer: It uses frappe.utils.preview.get_preview_from_html, which utilizes a native headless Chromium via CDP (Chrome DevTools Protocol). It reuses the existing ChromiumManager from the PDF generator.
    • Asset Resolution: The renderer sets the tab URL to the host before injecting content, ensuring that internal assets like fonts (/assets/...) and logos (/files/...) resolve correctly from the disk.
    • Security: The rendering utility is not whitelisted for arbitrary HTML to prevent SSRF (Server-Side Request Forgery) vulnerabilities; it is intended to be called in-process with controlled HTML.
    • Storage: Generated images are stored in private/files/wiki-og/ using a fingerprint-based naming scheme to ensure freshness without requiring manual invalidation hooks.
    # Framework utility used for rendering
from frappe.utils.preview import get_preview_from_html

# Example usage (internal logic)
image_bytes = get_preview_from_html(html, format="jpg", width=1280, height=720)

  9. BreadcrumbList JSON-LD Implementation

    develop

    To improve search engine visibility, Wiki documents include BreadcrumbList JSON-LD structured data in the public <head>.

    Breadcrumb Logic

    The breadcrumb trail follows the hierarchy: [Space, Page].

    • Space: The item in the breadcrumb links to the space's root route (which 301 redirects to the space's default page).
    • Intermediate Groups: Sidebar groups that act as non-clickable toggles are excluded from the JSON-LD trail to comply with Google's item-URL rules.

    Security

    The JSON-LD output uses json.dumps with escaping to ensure that hostile characters (like <) are converted to unicode escapes (e.g., \u003c), preventing XSS attacks via document titles.

  10. Frontend: Tab Bar Rendering and Responsiveness

    develop

    The WikiTabBar.vue component renders a horizontal row of tab groups.

    Key Behaviors:

    • Active Tab Detection: The system identifies the active tab by walking the current page's ancestors in the loaded tree. No additional route parameters are required.
    • Responsive Design: Below a specific breakpoint, the tab bar collapses into a <Dropdown> trigger that lists all available tabs.
    • Integration: The bar is rendered in SpaceTreePanel.vue and SpaceDetails.vue only when the Space contains at least one tab (is_tab=1).

  11. Handle text selection and menus on mobile

    develop

    To avoid conflicts with native OS text-selection toolbars, the following mobile-specific behaviors are implemented:

    • Bubble Menu: The WikiBubbleMenu.vue is disabled on mobile (isMobile returns false). Users should use the sticky top toolbar or the slash menu instead.
    • Slash Menu: The slash menu uses tippy with popperOptions configured for mobile: flip (with fallbackPlacements: ['top-start','bottom-start']) and preventOverflow (with boundary: 'viewport'). This ensures the menu flips above the caret if the software keyboard covers the bottom of the screen.
    • Slash Menu Item Sizing: .slash-command-item elements are given a min-height: 44px on mobile to ensure they are easily tappable.

  12. Mermaid diagram Markdown syntax and rendering

    develop

    To create a Mermaid diagram, use a standard Markdown code fence with the mermaid language tag.

    Markdown Input:

    ```mermaid
[Mermaid syntax here]
```

    HTML Output (Public Reader): The server-side Markdown processor (markdown.py) intercepts these fences and converts them into a specific HTML structure for client-side hydration:

    <pre class="mermaid">[HTML-escaped source]</pre>

    Behavioral Notes:

    • No-JS Fallback: If JavaScript is disabled, the raw source code is displayed within a <pre> tag (via <noscript> fallback).
    • Performance: The Mermaid library is loaded lazily. It is only fetched if the page contains at least one .mermaid container, ensuring diagram-free pages do not incur the overhead of the Mermaid library.