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/<workspace>/doc-name

The prefix is your workspace slug — the one you (or a teammate) chose during onboarding, not your personal username. That URL stays stable: when you update the document later, readers keep using the same link.

Every workspace has a Default project. If you never create another project, docs appear directly under the workspace:

https://opendocs.cc/<workspace>/doc-name

For larger batches, agents and CLI users can create named projects. Project docs use a project-scoped URL:

https://opendocs.cc/<workspace>/projects/<project>/doc-name

Projects are best for things like launch plans, client deliverables, research batches, and feature-specific docs. Tags still work inside each project, so you can combine both: project for the body of work, tags for topics inside it.

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.
  • Projects keep agent-generated batches from cluttering the main workspace.
  • 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.