Skip to main content

How OpenDocs works

OpenDocs is intentionally narrow:

publish(markdown) -> stable URL

It is not trying to replace your editor, notes app, repo, or AI tool. Instead, it turns Markdown that already exists in your workflow into a readable web page.

The source of truth stays local​

Your original Markdown file stays on your machine, in your repo, or in the tool that generated it.

When you publish, OpenDocs stores:

  • the raw Markdown snapshot
  • rendered HTML
  • table of contents data
  • metadata such as title, slug, tags, and visibility
  • version history

Publishing creates a stable URL​

When you publish a file, OpenDocs generates a canonical URL like:

https://opendocs.cc/you/doc-name

That URL stays stable. When you update the document later, readers keep using the same link.

Visibility is private-by-default in spirit​

The default CLI visibility is workspace, which is the safe “share with my team” mode.

  • private: author only
  • workspace: active workspace members
  • public: anyone with the link

Public visibility always requires explicit confirmation.

Rendering behavior​

OpenDocs currently supports:

  • Markdown with GitHub Flavored Markdown features such as tables and task lists
  • syntax-highlighted code blocks
  • automatic heading anchors and a table of contents
  • title inference from frontmatter or the first # Heading

It also strips fenced private blocks before rendering:

```private
Internal notes that should not appear in the published version.
```

Updates create versions​

Each update stores a new version number instead of replacing the old record in place. The public CLI is centered on publish, update, list, get, pull, and unpublish, while version history is preserved on the server.

Why teams use it​

  • AI tools generate lots of Markdown that needs a shareable URL fast.
  • Teammates should be able to read without cloning a repo or installing a notes app.
  • Sharing should be controlled, with workspace-first defaults and public opt-in.