Why plain text ages well
Markdown provides readable source files that remain useful without the editor that created them. Its strength is not that all parsers render identically—Markdown has dialects—but that headings, lists, links, and code fences are easy for humans and basic tools to understand.
Use UTF-8, descriptive filenames, and a small number of conventions. Keep the plain-text source canonical; exports such as PDF are derivative artifacts. A note should remain legible in a terminal even when a preferred application is unavailable.
Make the structure intentional
A minimal document might look like this:
# Incident: TLS renewal did not deploy
## Symptom
The endpoint continued serving an older certificate.
## Evidence
- Renewal completed without error.
- The service had not been reloaded.
## Resolution
Verify the installed path and add a controlled reload hook.
That format supports both a future reader and a simple search tool. It does not depend on a particular proprietary database or plugin.
Metadata should help, not dominate
YAML front matter is a convenient convention for structured attributes, but it is not part of every Markdown implementation. Avoid making your archive unusable when a tool ignores front matter. Put the document's central meaning in its body, not only in tags.
Choose a small set of fields: title, type, source, and review trigger are often sufficient. Dates should represent real events, not synthetic freshness signals. Avoid storing secrets or credentials in ordinary notes merely because the format makes them easy to paste.
Links and attachments
Prefer relative links for content that travels together. Keep attachments in predictable directories and describe their meaning. For example:
[Network diagram](../assets/network-topology.svg)
[Related decision](../decisions/tls-termination.md)
Use stable file names before creating lots of links. If you rename notes, let your editor update links or run a link checker. An archive that contains dead links is technically portable but operationally fragile.
Backups and versioning
Git provides a readable history for text notes, but a repository is not a backup by itself. Maintain an independent copy and test restoration. Large binaries and confidential material may be better managed separately. If synchronization introduces conflicts, preserve both versions until differences have been reviewed.
# Find Markdown files without a particular file manager.
find . -type f -name '*.md' -print
# Locate a phrase in the archive.
rg -n -i 'certificate renewal' --glob '*.md' .
Notebook principle: use tools that make plain text more useful, rather than tools that make plain text dependent on them.