Markdown makes written knowledge easy to move as text. A note can remain readable outside the application that created it, and its headings, links and code can be inspected without opening a proprietary document format. Moving the file, however, does not necessarily preserve its attachments, application features or rendered appearance.
That distinction matters when a personal note becomes team documentation or a repository README becomes a client report. A useful portability check asks what the next reader needs to understand, then checks whether the exported package supplies it. The review method below is editorial guidance, not a measured comparison of knowledge tools.
This chapter is part of The Markdown Layer. MD2FILE publishes the series and provides the editor mentioned here; that commercial interest does not establish the suitability of a format for every workflow.
What can travel inside a Markdown file?
A Markdown file can hold prose and structural conventions that remain understandable in a text editor. CommonMark provides a specification for interpreting that syntax. Its account of historical parser differences also explains why a document can render differently across implementations. A declared parser or dialect makes the expected behavior clearer. CommonMark specification.
Some familiar features belong to extensions. GitHub Flavored Markdown adds tables and task lists, among other features, and GitHub applies further processing to the resulting HTML. A .md suffix therefore gives an incomplete description of a document's rendering requirements. GFM specification.
This conceptual diagram separates the text file from the conditions needed to display it. Source can survive a move even when a diagram renderer, linked image or application-specific feature is missing.
| Part of a note | What the file can preserve | What needs a separate check |
|---|---|---|
| Prose and headings | Wording and visible structural markers | Heading hierarchy and generated anchor links |
| Code examples | The characters inside a fenced block | Language highlighting and line wrapping |
| Images | A path or URL, plus alternative text | The image file, access permissions and resolution |
| Tables and tasks | Source rows and task markers | Support in the destination dialect |
| Diagrams and equations | Source notation | Compatible rendering software and fonts |
| Application features | Sometimes a reference or special marker | Queries, embeds, plugin behavior and local configuration |
The table is a review aid. It does not imply that every application loses the same features or that a successful import preserves every meaning.
File ownership and application independence
Obsidian documents a concrete file-based model: notes are Markdown files in a local vault folder, and other editors can modify them. The application also maintains separate settings and a metadata cache. This illustrates why retaining readable files and retaining the complete application experience are different tasks. How Obsidian stores data.
For a long-lived knowledge collection, record which parts are ordinary files and which parts depend on software behavior. A folder containing notes and images is easier to inspect than a folder of notes that silently depends on attachments elsewhere. Keep a short description of required extensions beside the collection, particularly if a colleague will maintain it after the original author leaves.
Plain text also exposes changes to review. A reviewer can inspect a changed sentence without interpreting a page-layout file. That does not make every change meaningful: automatic wrapping or regenerated output can still obscure substantive edits. Teams should agree on a small set of formatting conventions that make their own reviews manageable.
The existing Markdown documentation guide covers the underlying writing patterns. Portability adds a further concern: whether those patterns carry enough context beyond the original workspace.
A README is a document inside a repository
GitHub resolves relative links and image paths using the file's location and branch. It also creates navigation from headings. When the README leaves that environment, a converter or publishing process must establish its own base location for relative references. GitHub's README documentation.
Consider an illustrative handbook package with three files:
handbook/
README.md
docs/
setup.md
images/
architecture.svg
The README contains these references:
# Project handbook
Read the [setup instructions](docs/setup.md).
docs/setup.md contains the setup instructions, and images/architecture.svg contains the diagram. Neither file is embedded in the README by those references. The package needs all three files; a .md file by itself carries only the link destinations and image alternative text.
Suppose the sender copies only README.md into delivery/README.md. In a viewer that resolves paths relative to that file, docs/setup.md now points to delivery/docs/setup.md, and the image points to delivery/images/architecture.svg. Those destinations do not exist in the one-file delivery. The original files remaining under handbook/ cannot satisfy those paths for a recipient who never received that folder.
For an editable offline handoff, the resolution is to copy the two dependencies with their relative paths intact:
delivery/
README.md
docs/
setup.md
images/
architecture.svg
The README links can now stay unchanged. The file inventory is complete for this example because the README has exactly these two dependencies, and we assume the setup page and SVG have no further external references. In a real package, follow references inside those files too. Open delivery/README.md in the intended viewer with delivery/ as its directory context, follow the setup link and inspect the diagram. A converter that accepts only pasted text needs its own asset-loading arrangement; this folder structure alone cannot give it access to local files.
This is a worked path-resolution example, not a recorded application test. A recipient who receives only a PDF needs a different handoff: include the essential setup instructions in the report or replace the relative link with a maintained destination they can access. Check the actual PDF's image and link behavior separately. Review access permissions before sharing material outside the team.
Our GitHub-Flavored Markdown export guide includes a downloadable README example. It is a practical way to inspect how source, an image and the resulting PDF relate; it is not evidence that every repository document exports identically.
Preserve the decision behind the prose
A note often relies on knowledge shared by its original readers. “Use the second option” may be clear beside a live conversation and meaningless six months later. Portable knowledge needs enough context to be understood without that surrounding screen.
For example, an illustrative engineering decision record could include:
## Decision: keep the existing import format
Status: accepted for the next release
Reason: the proposed replacement omits attachment references.
Scope: documentation imports; other integrations are unchanged.
Evidence: link to the reviewed sample and issue.
Revisit when: the replacement preserves the required references.
The value comes from the explanation and references, not the filename extension. Add the actual decision date and responsible owner when creating a real record. Separate a decision from a suggestion, and identify what evidence could change it. Avoid leaving example placeholders in a published document.
For knowledge that also directs an AI tool, instruction scope and authority introduce additional concerns. Those belong in Markdown and AI agent instructions, rather than being assumed from the readability of a note.
Choose the output for the next reader
| Reader's task | Useful handoff | Main review question |
|---|---|---|
| Continue editing | Markdown with required assets | Can the recipient edit and rebuild it? |
| Read a maintained reference | HTML with stable navigation | Are links, headings and revisions understandable? |
| Review a fixed issue of a report | PDF plus its source where appropriate | Are pages legible, searchable and clearly versioned? |
| Reuse measurements | CSV or JSON with definitions | Are units, missing values and populations explicit? |
Several outputs can coexist. A report can have a canonical HTML page, a dated PDF and a small data download. Keep their version information consistent so a correction in one format does not leave the others looking authoritative but stale.
The MD2FILE editor is one option for reviewing Markdown before producing PDF or HTML. Standard document processing happens in the browser, while optional AI and cloud features have different data paths; consult the privacy policy for that boundary. The PDF review checklist covers the output checks that remain after the text is ready.
Before handing over a knowledge package, open it outside the original workspace, follow its essential links and inspect its images. Ask a reader who lacks the original context to identify the decision, evidence and current status. Record the format, assets and version that passed that review so the next revision has a concrete starting point.
Part of The Markdown Layer: State of Markdown 2026. Previous: maintaining agent documentation · Research overview · Next: checking a Markdown PDF · Methodology and limitations.