A README is easy to review in a repository, but the same information may need to travel as a stable document for a meeting, handoff, or archive. Converting Markdown to PDF is useful when the source should remain plain text while the delivered copy needs pages, margins, and selectable text. The important part is not merely obtaining a file ending in .pdf; it is checking that structure, links, tables, and code still communicate correctly after pagination.
This guide builds one reproducible README and converts it with the Markdown to PDF tool. UtilX processes the input in the browser and exports only when requested. The worked example uses no confidential data and states what can and cannot be inferred from the preview.
Define the document before formatting it
Markdown describes structure with plain-text conventions. CommonMark distinguishes blocks such as headings, paragraphs, quotations, lists, thematic breaks, and code blocks from inline content such as links, emphasis, and code spans. GitHub Flavored Markdown adds tables, task-list items, and strikethrough. A converter must map those structures onto a page model; it cannot preserve the fluid width of a browser exactly.
Start with the purpose and reader. For this example, a small team needs an offline release checklist. The PDF must be readable on A4 paper, retain clickable HTTPS links, show code as code, and make completed tasks distinguishable. Those are verifiable requirements. “Looks identical everywhere” is not: the preview and the PDF use different layout engines, so line wrapping and page breaks can differ.
A worked README example
Create release-readme.md with the following synthetic content. It exercises supported syntax without depending on remote files:
# Atlas 1.4 release
**Owner:** Docs team
*Window:* 18 September 2026
~~Old target: 1.3~~
> Ship only after the rollback check passes.
## Checklist
- [x] Freeze translations
- [ ] Publish package
- [x] Verify checksum
- [ ] Copy the release note
## Commands
Run `npm test`, then:
~~~sh
npm run build
npm run smoke
~~~
## Environments
| Name | URL | Owner |
| --- | --- | --- |
| Staging | [status](https://example.com/status) | Platform |
| Production | pending | Operations |
---
See the [runbook](https://example.com/runbook).
The expected PDF contains one main heading, three metadata items—owner, window, and a struck-out former target—a quotation, a nested task list, inline and fenced code, a three-column table, a separator, and two links. The exact page count is deliberately not specified: it depends on paper size, margins, font size, and wrapping.
Convert and verify it step by step
Open the localized tool and paste the example or import the .md file. Keep the source under 200 KiB in UTF-8; larger input is rejected before parsing. Inspect the preview for hierarchy rather than page boundaries. Confirm that the heading is stronger than body text, completed and open tasks are distinct, nested items remain under their parent, and the table has three aligned columns.
Choose A4, 20 mm margins, 12 pt body text, and page numbering. Give the download a descriptive name such as atlas-1-4-release.pdf, then export explicitly. Nothing should download merely because the source changed. Open the saved PDF in a separate reader. Select and copy a sentence to confirm that the body is text rather than a page-sized screenshot. Search for rollback, activate both HTTPS links, and zoom into the command block and table.
Repeat once with Letter paper if the recipient prints in that format. Compare meaning and legibility, not coordinates. A narrow table may wrap differently; a heading may move to the next page. If a row becomes hard to read, shorten cell content or restructure it as a list instead of shrinking the entire document.
What the options actually change
A4 and Letter have different dimensions, so the same paragraph can occupy a different number of lines. The 12, 20, and 28 mm margin choices change the available writing area. Body sizes of 10, 12, and 14 pt change density and accessibility. These controls interact: increasing both margins and type size produces earlier wrapping and usually more pages.
Page numbers are optional output furniture. They help discussion of a static copy, but they are not part of Markdown itself. PDF generation lays content out into a fixed page size and can place a dynamic number in a footer. The exported document keeps text selectable and supported links active. The preview is an honest approximation of styling and order, not a guarantee of identical pagination.
The supported first-version set covers headings, paragraphs, bold, italic, strikethrough, HTTP(S) and mailto links, nested ordered or unordered lists, task lists, quotations, separators, inline and fenced code, and GFM tables. That list matters because Markdown dialects differ. A construct working in one repository extension does not imply that every converter understands it.
Troubleshooting common failures
If a list loses nesting, inspect indentation and leave a blank line around neighboring blocks. If a table renders as literal pipes, ensure it has a header, a delimiter row, and the same logical columns in each row. If code consumes unexpected formatting, close its fence with the same marker and at least the opening length. These checks follow the block rules rather than relying on visual spacing in one editor.
Remote images and local file references are not loaded. The converter outputs their alternative text and a warning so the omission is visible. Write meaningful alt text and attach approved images separately if the final workflow requires them. Raw HTML is displayed literally with a warning; it is not executed. Do not use an HTML tag as a workaround for unsupported layout.
If export stops, check UTF-8 size before reducing content. Splitting a large document into coherent chapters is safer than deleting warnings or code blindly. If a link fails, verify that it starts with https://, http://, or mailto: and test the exported PDF reader as well as the preview.
Choices for a durable handoff
Keep the Markdown as the editable source and treat the PDF as a dated output. Record the chosen paper, margin, font size, page-number setting, and tool date near the release process. Reviewers can then reproduce the export rather than editing an opaque PDF. For controlled documents, retain the source revision and the exported file together.
Use headings in order and descriptive link text. Do not rely on color alone for task state. Keep code lines reasonably short and tables compact; both structures have a natural width that paper may not accommodate. A list is often more robust than a table with long prose. Before sharing, read the PDF at normal zoom and with text selection or search, not only as thumbnails.
Browser-side processing reduces the need to send the entered Markdown to an application server for this conversion, but the downloaded file still enters the browser and operating system’s normal storage flow. Apply the same classification and sharing rules that govern any other exported document.
Boundaries of this converter
The first version does not render mathematics, Mermaid diagrams, custom HTML, or executable content. It does not fetch remote images or files. It does not promise pixel-identical preview and PDF pagination, archival conformance, tagged-PDF accessibility, digital signatures, encryption, or preservation of repository-specific plugins. A PDF that opens is not automatically accessible, approved, or complete.
Complex tables can still be poor reading material even when valid. To prevent clipping, PDF list indentation stops increasing after six nested levels, although the remaining content is preserved. A table is rejected when its available width would leave any column below 25 pt; split its columns or reduce the selected margins instead of forcing an unreadable export.
Very long unbroken strings or code lines may wrap awkwardly. The export adds legal wrap opportunities, and some PDF readers may insert whitespace when copied text crosses those wraps. If an exact command matters, copy the long line from the PDF and compare it character for character with the Markdown source before using it. Readers can also handle links and fonts differently. Test the actual exported file in its destination environment, and use a specialist publishing workflow when exact typography, advanced accessibility, or compliance is required.
Final verification checklist
Confirm that the source is UTF-8 and no larger than 200 KiB. Check headings, emphasis, strikeout, links, nested and task lists, quotations, separators, code, and tables against the intended meaning. Review every image warning and every literal HTML warning. Export with the agreed A4 or Letter size, 12, 20, or 28 mm margins, 10, 12, or 14 pt body text, and the chosen page-number setting.
Open the downloaded PDF independently. Select and copy text, search for a known phrase, follow every important link, inspect table columns and code, and read across page transitions. Compare content and hierarchy with the README without demanding identical preview pagination. Finally, keep the source and settings with the verified PDF so another reviewer can reproduce the result.
Sources: CommonMark specification, GitHub Flavored Markdown specification, and pdfmake document definition documentation.