openknowledge view

Start the local web viewer. Specify a path or registry key to open one knowledge base. Omit the target to open all connected knowledge bases in one registry workspace.

Usage

okn view [key-or-path]
okn view --no-browser Wiki
okn view --host 127.0.0.1 --port 8080 Wiki
okn view --allow-network --host 0.0.0.0 Wiki

Head injection also reads OPENKNOWLEDGE_HEAD_FILE, OPENKNOWLEDGE_HEAD_HTML, and OPENKNOWLEDGE_SCRIPT_SRC.

Viewer features

• The viewer renders Markdown and follows local links. It renders fenced mermaid blocks as diagrams. It also shows note panels, source graphs, validation context, highlighted assets, and media or PDF previews.
• Source and text files open as standard note cards. They use the same breadcrumbs, panel controls, syntax highlighting, and open-beside behavior. Other assets keep their raw or dedicated media previews.
• Click a rendered Mermaid diagram to open a viewport-filling dialog. You can also focus the diagram and press Enter or Space. Use the toolbar, wheel, or pinch gesture to zoom. Drag the diagram, or use the arrow keys, to pan. Select Fit to fit the complete diagram in the viewport. Select 100% to center the diagram at its original scale. Press Escape to close the dialog.
• The sidebar has separate Documents, Graph, and Knowledge bases items. Documents shows the active file tree. Graph shows the graph workspace. Knowledge bases lists every connected knowledge base and its file tree in registry mode. Use the collapse icon to close all expanded trees. Use the plus icon to connect another local folder. Settings opens the viewer preferences from the sidebar footer. Select the shortcut badge in the viewer header to open or close the file explorer.
• Open-beside mode is the default. The link behavior control can select the current panel mode. The browser stores this selection. Hold Shift during activation to use the other mode one time. Each panel keeps its own focus and close controls. The open file explorer remains visible during link navigation and uses the first grid column at 25vw by default. You can resize it within its minimum and maximum limits. The viewer header, note workspace, and horizontal scroll rail remain in the second grid column. With multiple panels open, drag the bottom horizontal scroll thumb to move the document stack directly.
• On viewports up to 680 px, sidebar open and close actions have no motion. Note stack navigation has no View Transition or fallback panel entrance effect. A sidebar link closes the sidebar and shows its destination immediately.
• AST-based search uses the same section ranking as okn search. It also uses the same one-level link expansion. Results group section matches by document. They can link to and highlight the matching text. Search excerpts strip common Markdown markup. The search control is on the right side of the viewer header. Registry mode searches all connected knowledge bases. Each result shows its source knowledge base. The viewer adds folder context to Index titles. The search panel shows progress, result counts, no-result messages, and errors. Select Retry after an error. Use the arrow keys to select a result. Press Enter to open it. Press Shift+Enter to use the other panel mode. Press Escape to close search.
• Each note uses a compact header. The full-width Frontmatter disclosure is immediately below the header and starts collapsed. Select Frontmatter to expand the full typed YAML table. When the registry workspace contains multiple knowledge bases, the header prefixes the path breadcrumb with the source knowledge-base name. The prefix uses the same breadcrumb style and slash separator. The viewer also provides tag filters, sortable tables, and directory breadcrumbs. The Documents view expands the active file branch. Directory rows can collapse, and the explorer has a Collapse all action.
• For OKF 0.2 concepts, the expanded frontmatter area groups derived trust, status, freshness, provenance, structured sources, and Attested Computation data. Each derived signal uses the same two-column field-and-value rows as the frontmatter table. The viewer marks inferred unverified trust and stable status values as Default. Source footnotes open the matching structured source entry. The viewer never executes declared resources automatically.
• The knowledge graph uses a theme-aware canvas. The left detail panel shows only the connection count for the selected or hovered node. The canvas aria-label keeps the node name and Enter hint. The top-bar Graph icon toggles between the graph and the open documents. On viewports wider than 680 px, the graph workspace fills the viewport below the header. The canvas is 380 px high on smaller viewports. On viewports up to 680 px, the Graph settings disclosure starts collapsed and contains graph filters, display and force controls, and reset and animation actions. Drag the canvas to pan. Use the wheel or trackpad to zoom. Icon-only zoom, fit, and settings controls sit in the canvas's lower-left corner. Graph settings are hidden by default. The settings control toggles a vertically centered card on the canvas's left. Drag a node to move it. Use the fit control to show the complete graph. Filter notes by title or path. The Color nodes by folder control applies theme-aware colors. Hovered and selected nodes keep their folder colors. Registry mode combines the graphs from all connected knowledge bases. It does not add links between knowledge bases. File-name labels use the source knowledge-base color. The file nodes keep their current graph colors. Display controls adjust arrows, labels, node size, and link thickness. Force controls adjust center, repel, and link forces. Select Pause to stop graph motion. Select Resume to start motion. Select Reset graph to restore the graph defaults. Arrow keys move the selection. Enter opens the selected note. The file tree stays in the file explorer.
• Use Settings to change browser-local themes, typography, line length, contrast, motion, and link settings. Reset to defaults restores the viewer defaults. The first visit uses the light blue default theme. A saved theme preference overrides this default. These preferences do not change source Markdown. The Horizontal stack switch is enabled by default in the Document section. Disable it to replace the current document when following a link.
• The browser assigns a color to each connected knowledge base. Use the color control beside its name to change the color. The browser saves this choice locally and reuses it in search results and graph labels.
• Direct paths and writable local connections provide local editor links. Static exports use configured repository source links.
• The local viewer serves the same Vite-built JavaScript and CSS bundle as static exports. Local routes supply live API data. Static pages load one shared generated data file.

The viewer selects the displayed brand from root metadata in this order: okf_bundle_title, okf_bundle_name, title, then the first H1. The viewer truncates long brand names with an ellipsis when header space is limited.

Network and file safety

Loopback mode does not require a token. A non-loopback or wildcard bind requires --allow-network. All routes then use token authentication.

The initial URL exchanges the token for an HttpOnly, SameSite cookie. It then redirects to a clean URL. A remote client can also send Authorization: Bearer <token>.

Raw routes serve only regular non-Markdown bundle assets. They exclude dotfiles, .git, .openknowledge.toml, legacy openknowledge.toml, and symlinks. Markdown and asset resolution cannot leave the bundle root.

The viewer inserts trusted head fragments in their original form. Use only content that you control.

In registry mode, the viewer rebuilds routes after the validated registry snapshot changes. It refreshes content-hashed search indexes after source edits. A registry or fingerprint failure returns an error. The viewer does not serve stale or partly trusted state.

The registry workspace can connect an existing local knowledge base. The connection is read-only unless you enable editor links. If the selected folder is not a knowledge base, the viewer shows the okn setup command that creates one. Direct-path and static-export views do not provide the registry connection control.

Theme and source-link configuration comes from .openknowledge.toml. For deployment, use the HTML exporter.