# Feature Request before PR: Document Tagging System

[defcon1702]

Summary

I would like to propose a tagging system for Outline that allows documents to be classified with tags as an orthogonal dimension alongside the existing collection hierarchy. One of the most requested features I found here in the community are tags.
I will be running Outline as the primary knowledge base and have found that the collection structure alone is not sufficient to express the full semantic context of documents, particularly across team boundaries and topic domains that naturally span multiple collections.

I am opening this discussion to align with the core team before submitting a PR.

---

The Problem

Outline's current document organization relies exclusively on collections and nested documents. This works well for hierarchical structure, but it creates friction in two common scenarios:

1. Cross-cutting topics that don't belong in a single collection

A document about "Q1 Budget Review" lives in the Finance collection — but it is equally relevant to the Strategy team, the Marketing team, and the Operations team. There is no lightweight way to express this relevance without duplicating the document, creating awkward cross-collection links, or building a deeply nested hierarchy that doesn't reflect how people actually think about topics.

Tags solve this cleanly: a document stays where it belongs structurally and gains orthogonal classification metadata.

2. Discoverability at scale

As a knowledge base grows past a few hundred documents, finding related content becomes increasingly difficult if the only navigation is the collection tree. Search helps, but it requires knowing what to search for. Tags allow users to browse by topic, status, project, or any other dimension the team finds valuable without restructuring the entire collection hierarchy.

---

More convient to tools like FSNotes and Obsidian.

I maintain an Obsidian vault alongside our Outline instance and have built a plugin that synchronizes Obsidian notes into Outline. Obsidian documents carry tags as YAML frontmatter (tags: [project, client-xyz]). Today, those tags are silently dropped when documents are pushed to Outline, losing valuable classification metadata that the vault relies on.

---

Proposed Design

After thorough analysis of existing approaches (including Obsidian, Notion, and Confluence), I propose a pure metadata classification system — not inline hashtags in document content.

Core principle

Tags are document-level metadata, stored separately from document content. This is the key decision that differentiates our proposal from a naive hashtag implementation:

• Renaming a tag is a single database update — it does not touch document content, does not create new revisions, and does not conflict with collaborative editing sessions (Y.js)
• Tags are visible to anyone who can read the document — including guests and public share recipients — without requiring team membership
• The tag autocomplete list (for editors creating new tags) is team-scoped, preventing tag proliferation and ensuring consistent naming across the workspace

Data model

Two new tables:

tags
├── id          UUID, PK
├── teamId      UUID, FK → teams.id, CASCADE DELETE
├── createdById UUID, FK → users.id, SET NULL
├── name        VARCHAR(64), stored as lowercase
├── createdAt / updatedAt / deletedAt (paranoid)
└── UNIQUE(teamId, name)

document_tags  (join table)
├── id          UUID, PK
├── documentId  UUID, FK → documents.id, CASCADE DELETE
├── tagId       UUID, FK → tags.id, CASCADE DELETE
├── createdById UUID, FK → users.id, SET NULL
├── createdAt
└── UNIQUE(documentId, tagId)

Tags are team-scoped for normalization (one canonical "marketing" tag per team, not one per document), but they are delivered as part of the document response — so any user with document read access sees them, independent of team membership.

Permission model

Action	Who
Read tags on a document	Anyone with document read access (including guests and share links)
List team tags (autocomplete)	Team members only — not guests
Add / remove tag on a document	Editors with document update permission
Create a new tag	Editors (upsert on addTag by name)
Rename a tag (affects all documents)	Team admins only
Delete a tag globally	Team admins only, with explicit confirmation

Deletion safety mechanism

Deleting a global tag removes it from every document in the team. This is a destructive, team-wide operation.I propose a two-step confirmation:

1. POST /api/tags.usage returns the document count per tag
2. The frontend shows a confirmation dialog listing the impact before allowing the delete
3. POST /api/tags.delete requires { confirm: true } in the request body — a request without the confirmation flag returns HTTP 400

API surface

Following the existing RPC-style POST pattern used throughout the Outline API:

POST  /api/tags.list        List team tags (paginated; supports query for autocomplete)
POST  /api/tags.create      Create a new tag (name, optional color)
POST  /api/tags.update      Rename or recolor a tag (admin only)
POST  /api/tags.usage       Usage count per tag + document count (pre-delete preview)
POST  /api/tags.delete      Delete tag globally (admin only, requires confirm: true in body)

POST  /api/documents.addTag     Add tag to document (accepts name or id; upserts new tags)
POST  /api/documents.removeTag  Remove tag from document

The documents.addTag endpoint accepts a tag by name (not just ID), and upserts the tag if it does not yet exist. This is essential for programmatic use cases like our Obsidian sync plugin.

Document response extension

{
  // ... existing fields ...
  tags: Array<{
    id: string;     // omitted in isPublic / share-link responses
    name: string;
    color?: string; // optional hex color, e.g. "#4caf50"
  }>;
}

Tags are included in presentDocument for both authenticated and public (share-link) responses. In the public case, id is omitted to prevent enumeration of internal resources.

Markdown import / export (YAML frontmatter)

YAML frontmatter tags: is a widely used open standard (Jekyll, Hugo, Pandoc, Ghost not Obsidian-specific). I propose:

• Import: When a Markdown file is imported and contains tags: in its YAML frontmatter, those values are automatically set as Outline tags on the document
• Export: When a document is exported as Markdown, its tags are written as tags: in the YAML frontmatter

This makes Outline a first-class citizen in Markdown-based workflows and enables round-trip compatibility with tools like Obsidian.

---

What I'm explicitly NOT proposing

To keep the scope focused and the implementation maintainable:

• No inline hashtags in document content. Outline already has document linking ([[Doc]]). Inline tags would create a second, weaker navigation system with significant editor complexity (ProseMirror extension required) and bidirectional sync problems in collaborative sessions.
• No nested / hierarchical tags (#project/sub). Flat tags are sufficient and far simpler to implement and maintain.
• No per-user tags. Tags are team-wide normalized identifiers — marketing means the same thing for everyone on the team.

---

Implementation Status

I have a working implementation in a local fork covering:

• Database migrations for tags and document_tags
• Sequelize models and BelongsToMany relation on Document
• Policy layer following existing cancan patterns
• API routes including the usage preview endpoint
• presentDocument extension (with and without id for public responses)
• YAML frontmatter import/export integration
• Frontend: MobX model and store, TagBadge and TagInput components (with autocomplete, click-to-assign, and colored dot indicators), sidebar integration, admin settings page with color picker, rename, and two-step delete

I'm are happy to submit a PR once there is alignment from the core team on the approach. I'm also open to adjustments particularly around the API naming conventions and where tag management surfaces in the Settings UI.

---

Prior Art / Related Discussions

Tags have been discussed in Outline's community before. This proposal attempts to synthesize those discussions into a concrete, fully specified design that is ready for implementation. Key decisions that differentiate this proposal from previous ones:

• Tags are metadata, not content — no editor extension required in Phase 1
• Team-scoped normalization prevents the tag proliferation problem that plagues content-embedded approaches (a known pain point in Obsidian)
• The permission model carefully separates "reading tags" (document access) from "managing tags globally" (admin access)
• Deletion is protected by a two-step mechanism that shows impact before committing

---

Questions for the Core Team

1. Is the proposed API naming (documents.addTag, documents.removeTag) consistent with your conventions, or would you prefer a different pattern?
2. Is the Settings page the right home for team-wide tag management, or would you prefer it to live elsewhere?
3. Do you have concerns about the YAML frontmatter import/export approach, or is that aligned with the direction for Markdown compatibility?
4. Are there any architectural constraints I should be aware of before I finalize the PR?

I'm looking forward to the discussion. Happy to provide detailed technical informations or a demo on request.

Some Screenshots:

[xbreaker]

+1.
Tags are the first thing that should be implemented in any notebook. Because for example I don't want a Java collection, but I want to tag documents with a Java tag for better search and order.

[pavelcdn]

It looks great, but I hope tags can be created directly on the content page, and not only in the admin panel

[defcon1702]

Sure. The panel you see let you choose from existing ones, the input has suggestion from existing tags and else a new one will be created. Only "bummer" in the moment, you need to config a color in the settings. I guess I will improve this.

[IamTaoChen]

Maybe you can create a PR at first?

[defcon1702]

No PR without discussion was the description in the repo, right? :)

[defcon1702]

I have edited the post to offer a proper informationbase and details before submitting a PR.

[xbreaker]

But we can discuss in a PR too

[tommoor]

Overall it's close to what I would be build and the high level architectural and design decisions are good, some concerns and questions that we'd need to work through. Top of mind for discussion:

UI

• I would not put tag management in the sidebar, a popover would be sufficient and lighter weight
• Color picker looks custom, we already have several built in
• Mixture of # icon and colored circles is going to look messy, should probably pick one.
• Tags should have essentially no surface unless used, .e.g no "Tags" section in the sidebar etc.
• How are tags ordered in the sidebar? It looks like alphabetical, is that useful? What if there are thousands of tags in the workspace? I'm not sold that a giant list of tags in the sidebar is desirable at all. Perhaps we should just let you star tag pages you're interested in.
• Related to above, we should allow starring a tag.
• CMD+K integration, shortcuts

Performance

• I am very hesitant to introduce an additional join to every document retrieval. It might be worth looking at a cached field on document instead similar to the comment.reactions JSONB. This introduces additional write complexity, but pays dividends on our most common reads.
• Tags should have a cached document count column, we have a pattern for this
• How are tags loading into the sidebar, are we now waiting for all tags in the workspace to be loaded on app load as well?
• How do tags interact in search? At the least it seems there should be a filter

API

• documents.addTag should probably be documents.add_tag to match add_user, add_group etc.
• Including frontmatter in Markdown export should probably be a preference

[defcon1702]

Is it possible for tags to be nested?

Not in this version and this would add a lot of complexity and performance issues.

[IamTaoChen]

Not in this version and this would add a lot of complexity and performance issues.

I see.

[defcon1702]

@tommoor Hey Tom what do you think about the video? Should we add a small mockup for a faster progress? :)

[tommoor]

I understood that the sidebar was just a temporary slide out element, I still think it would be better more like a lightweight multi-select menu that appears over the document rather than causing layout shift.

Please feel free to put in a PR and we'll see how far away the code is 👍

[defcon1702]

@tommoor PR is commited. :) Feel free to reach out with further questions. I tried my best to create transparency.
#11722