The philosophy of Contentmunch

The short version

If you read nothing else, read this. Each line is a rule the platform enforces, and the rest of the page says why.

Where these ideas come from

Contentmunch did not start from a blank page. It comes from more than a decade of running a large university's knowledge base: writing the software and working every week with the editors who used it. The same failures kept coming back, however good the people were.

Good people do not fix that. Tools do, and only the ones that make the right thing the easy thing. So the rules on this page are not preferences. They are what that decade taught, enforced by the software instead of left to habits a team will eventually drop.

Many details exist because they were once wrong in front of the editor who had to live with them. You get details like that from building with the people who use the thing, every week, not from a specification.

The problem being solved

Knowledge bases do not fail loudly. They rot, almost always the same way. A fact is copied into five documents; one copy is updated and four are not. Nobody knows which is right, or which documents are affected when something changes. A page is renamed and a link breaks. A note is deleted and nobody realizes something depended on it.

Each principle below removes one part of that decay.

Single source of truth

Say a thing once. Use it everywhere.

A fact lives in exactly one note. Any other note that needs it pulls it in as a live reference, never as a copy. We call this a boiler: the including note always shows the source's current content, so when the source changes, every note that includes it follows, without anyone saving it.

Why: A copy is a promise to keep two things in sync, and that promise always breaks in the end. A reference makes it structural, so there is nothing left to forget.

Whole notes only

A boiler pulls in a whole note, never a slice. We started with heading-level reuse and it did not survive Markdown: a heading has no closing marker, so "where does this section end" breaks when content is reordered, and a small wording fix to a heading breaks every reference into it. If you need only part of a note, move that part into its own small note and reuse that.

One level deep

A note is either a source or a consumer, never both, and a save that breaks this is refused. The editor checks that a reuse is well-formed as you type, but only the server knows the whole dependency graph, so the server decides, for every client.

Why: This is not a technical limitation: chains are easy to build. We rejected them because they destroy what makes "this changed, please look" worth sending. With one level, every consumer's dependencies are flat and you can list them. After four hops, a notification says almost nothing about why a document needs attention.

Reference by identity, resolve by name

Every note has a permanent identity that never changes, even when the note is renamed or moved. References point at that identity, never at a title or a location. Titles, captions and display text are resolved live, when they are shown, and nothing about them is copied into the note that refers to them.

Why: If nothing was copied, nothing can go stale. Renaming breaks no link, and no background job has to catch up on renames.

An address that says nothing

A name that describes content is a liability: the content changes, the name follows, and every reference breaks. So identity is kept separate from meaning. It is four random letters, assigned once, and a note's address is that and nothing else. The workspace comes from your session, never from the address. If you ever need a different identity, make a new note and archive the old one, so nothing that pointed at it breaks.

Frozen text is a choice

Sometimes you want text frozen, such as a label that should never follow its target. You mark a reference as static (links, titles, videos, images and documents can be), on purpose and never by accident, and a static reference stays out of the dependency graph because it follows nothing. Alt text is the exception: it has no frozen version, because it describes what the image is, not how one note frames it.

Canonical placement

Every piece of knowledge has one home, and everything else points there.

Notes, shared content, outside content and uploaded media each have one home, as the other principles describe. Terms get one too. A note can claim a term, which we call a hot item. The claiming note becomes the definition of that concept across the whole knowledge base, and any note that mentions the term can link to it.

One owner per term

Only one note can own a term. A conflicting claim fails the save, and the system never picks a winner: no override, no last write wins. To move ownership, release the term first. Search and AI can suggest terms a note might own, but ownership is never computed from similarity scores.

Why: If ownership shifted by itself, links would slowly retarget, which defeats the point of a canonical reference. A tool can inform that decision. It should not make it.

• Claiming and referencing are two different acts. Writing a reference never claims a term, even an unclaimed one.
• Linking is something you do, never a side effect of saving. A term link resolves live, and shows as unresolved, not silently broken, if the term is released.

Control what you own, verify what you don't

Two kinds of content need different treatment, because they have opposite properties.

Why: Pretending outside content is permanent gives you quietly broken links. Pretending your own content might change gives you machinery you do not need. Each kind gets the one guarantee that is actually available for it.

Know what depends on what

Every reference is tracked in one shared graph: links between notes, outside links and videos, images and documents, polls, forms and API operations. You can see what a note references and what references it. Two protections rest on it:

• Deletion is blocked while anything still depends on a note, and you are told exactly what, so the choice to unlink or keep is an informed one.
• Archiving is permanent and safe. An archived note's outgoing references become plain content, so it depends on nothing and nothing that depended on it breaks. Its Archived title prefix travels wherever it is reused.

Why: The dangerous failures in a knowledge base are the silent ones. Visible dependencies turn "I didn't know that was used elsewhere" into a question you can answer before you act.

Humans decide, the system informs

The platform tells you what needs attention. It does not make judgment calls for you.

• Content is never held back waiting for approval. When a source changes, consumers show the new content at once, and review runs alongside to say "this went live, and someone should look". (Making a note public is the one deliberate gate: see Publishing is a decision.)
• The author answers one question when saving a shared source: does this change what the content means to the notes that use it, or is it only wording or formatting? A person always knows. An algorithm guessing from edit distance cannot tell a typo fix from a small but critical change. A save with no edits skips the question, and an answer left out counts as yes.
• Review reminders are time-based, not opinion-based: a note can carry a cadence (monthly, quarterly, yearly, or never), and the system nudges when it passes, without claiming the content is stale.
• AI assists, but people accept. Generated answers are shown for approval before anything is saved, and a rejected answer leaves no trace.

Why: Where the signal might be missing, the platform assumes review is needed. An unnecessary review costs one click. A silently skipped one costs a stale document nobody knew to check. We will take the click.

Markdown is the source of truth

Notes are written in Markdown, with a visual editor on top. Markdown is what is stored, versioned and compared; rendered output is derived from it, never the other way round.

A note is rendered through one pipeline, the same one you see in your preview. What is saved and served is a capture of that preview, not a second rendering, and the server never parses Markdown itself. Two rendering paths will eventually disagree. With one, what you see is what is stored and what other applications receive. The server still checks every save for well-formed, safe output, because the client is never the only line of defense.

Fail loudly, or stay present

Not every derived field is treated alike when a note is saved again, and the difference is deliberate. Reused content and the table of contents are cleared until recomputed, because they have a right or wrong answer and failing loudly beats serving a mismatch. Search text and the meaning-based index are kept until replaced, because they only rank results, and slightly stale beats a note that cannot be found.

Never lose work

• Every note keeps its complete edit history. Browse or compare any past version at any time.
• Two people editing the same note cannot silently overwrite each other. The second save is rejected, with a clear warning and a way to copy your changes before reloading.

Why: Version history is the real safety net, so conflict handling does not need an elaborate merge tool. If nothing is ever unrecoverably lost, a rejected save is an inconvenience, not a disaster.

Control who sees what, down to the paragraph

A page often holds something not everyone should see: a salary band, a client's details, a security step. Every person has a role (reader, editor, publisher or administrator), and parts of a note can be limited to some roles.

• A reader who should not see a part never receives it. It is not sent and then hidden.
• Restricted text is also kept out of the tools that read for everyone: AI summaries, quizzes and answers, the search index and its snippets, and the terms offered as links.
• Asking about a restricted passage is refused, not answered from a partial view, and suggested edits never send a restricted section anywhere.

Why: If a tool can read text, it can repeat it. The safe place for restricted text is outside every tool that is not the intended reader.

Publishing is a decision, not a side effect of saving

A note is public, meaning reachable by an outside site, only when it is published. New notes start unpublished. A published note changes only through people who can publish, and every publish and unpublish is recorded in a log that cannot be edited.

• Someone who cannot publish asks for review. A publisher publishes the version they read, or sends it back.
• A published note can include only published notes, so what it shows is itself public, and a note it includes cannot be unpublished from under it.
• An outside site keeps its copy through a feed: an ordered list of what changed, reporting each note's current state, so a read that arrives twice or out of order does no harm.
• An organization that does not want the two steps can switch them off, and then saving makes a note live.

Why: Whether something is public should be an act someone can point to. A slower publish costs a click. A draft that went out cannot be taken back.

Knowledge is meant to be used

Notes are not a destination, they are an input.

• Search understands both the exact words you type and the meaning behind them. It also learns which searches come up empty, so the gaps in your notes become visible. A search that finds nothing is the most honest feedback a knowledge base gets.
• Quizzes and flashcards turn notes into active recall. A weak result is feedback on the note as much as on you: an unfair-feeling question usually means the note is unclear.
• AI assistance draws on what you have already written, not only on the current conversation.
• Other applications can query the platform and receive curated, ready-to-use content, resolved once and served consistently, so two applications never disagree about what a note says. Pulling should be easier than copying, so there is never a reason to paste a copy that will drift.

Keep it simple and build on what exists

Contentmunch is deliberately resistant to feature sprawl. Every feature has to be understood, documented and kept correct for as long as the product lives.

• New capabilities map onto the closest existing pattern before a new concept is introduced. A new kind of reference reuses the same graph, the same deletion protection and the same live-resolve behavior as the ones before it.
• New abstractions wait for a second real use case. Generalizing from one example usually gives you the wrong abstraction.
• One component, one behavior. Something that appears in several places looks and acts the same in all of them.

Why: Every feature has to earn its place, because everything we add is something we then have to keep correct. We would rather do fewer things and have each one behave the same way everywhere.

Read next

• How AI works: it runs only when asked, and never sees restricted text
• The privacy policy: what is collected, where it is kept and for how long