How to show a github-styled readme on your portfolio
- Step 1Pick the doc to feature — Choose the README or write-up that best showcases your work. Paste it or upload the single
.mdfile. - Step 2Render to GitHub HTML — Click Run. marked converts with GFM and the dark Primer theme is applied. No options to configure.
- Step 3Decide: whole file or just the body — Use the full HTML document as a standalone page, or copy only the
<body class="markdown-body">...</body>content to embed inside your existing page. - Step 4Wire up the CSS — If embedding the body, add the Primer
<link>to your page<head>(or inline the stylesheet) so the styling applies. Keep the content inside.markdown-bodyso it stays scoped. - Step 5Handle images and links — Switch any relative image paths to absolute URLs so they load on your live site, and confirm external links open correctly.
- Step 6Light-site adjustment (optional) — For a light portfolio, swap the
<link>to thegithub-markdown-lightbuild and adjust the inline background colours, or render with md-to-html for a neutral self-contained doc.
Embedding approaches
Three ways to put the output on a portfolio, with the trade-offs of each.
| Approach | What you copy | You also need |
|---|---|---|
| Standalone page | The whole HTML document | Nothing — but it needs internet for the CDN theme; dark-only |
| Embed the body | <body class="markdown-body">...</body> content | Add the Primer <link> (or inline CSS) to your page head |
| Inline everything | Body + the Primer CSS pasted into a <style> | Manual step; gives a self-contained, offline-safe block |
| Light-theme embed | Body + swapped light <link> | Use the github-markdown-light build and lighten the background |
Portfolio content: what renders
marked 14.1.4 default config determines feature support — the same as everywhere else this engine is used.
| Doc element | Status | Note for portfolios |
|---|---|---|
| Tables, lists, headings | Supported | Core structure renders cleanly |
| Code blocks | Supported (no colour) | language-xxx class is present; add a highlighter on your site if you want colour |
| Task lists, strikethrough | Supported | Render like GitHub |
| Relative images | Needs fixing | Use absolute URLs so they load on your live domain |
[!NOTE] callouts / footnotes / math | Not supported | Avoid relying on these in a featured doc — they degrade to text |
Cookbook
Practical embedding snippets. The output document's <head> is the same each run; the parts you act on are shown.
Embed just the body in a portfolio section
Lift the rendered body and drop it inside your page. Add the Primer link to your head so it styles.
In your portfolio page <head>: <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.5.1/github-markdown-dark.min.css"> In your page body: <section class="markdown-body"> <!-- paste the rendered body HTML here --> <h1>Project Atlas</h1> <p>A distributed task scheduler ...</p> </section>
Keep styles scoped with .markdown-body
Primer's rules target .markdown-body. Wrapping the content in that class prevents the GitHub styling from affecting the rest of your site.
Good (scoped):
<section class="markdown-body"> ...rendered doc... </section>
<footer> ...your own styles, untouched... </footer>
Bad (styles leak):
<!-- rendered headings/tables without the wrapper class -->
<!-- Primer's base rules may then not apply at all, or you
hand-copy them onto the wrong elements -->Fix relative images for a live domain
Relative paths that worked in the repo will not resolve on your portfolio host. Switch to absolute URLs.
Before (won't load on your site):  After (loads anywhere):  Then re-render so the output references the absolute URL.
Make it self-contained for a static export
If your portfolio is a static export that may be viewed offline, inline the Primer CSS instead of linking it.
1. Download <name>-github.html 2. Open the cdnjs URL in the <link>, copy the CSS text 3. Replace the <link> tag with: <style> ...pasted Primer CSS... </style> Now the file styles without a network call. Alternatively render with md-to-html, which inlines styles for you.
A code-block-heavy write-up
Technical write-ups lean on code. They render boxed and monospaced; add a highlighter on your site for colour.
Input:
## Retry logic
```go
for i := 0; i < maxRetries; i++ {
if err := call(); err == nil { break }
}
```
Output body:
<h2>Retry logic</h2>
<pre><code class="language-go">for i := 0; i < maxRetries; i++ {
if err := call(); err == nil { break }
}
</code></pre>Edge cases and what actually happens
Body is not self-contained without the CSS link
By designCopying just the rendered body gives semantic HTML but no styling unless your page also includes the Primer <link> (or you inline the CSS). It is not a self-contained block out of the box. Add the <link> to your page head, or inline the stylesheet for an offline-safe export.
Styles bleed into the page without .markdown-body
ExpectedPrimer scopes its rules to .markdown-body. If you paste the content without that wrapper class, the GitHub styling may not apply at all. Always keep the rendered content inside a class="markdown-body" element.
Relative images do not load on the live site
Expected./docs/arch.png resolved in the repo but not on your portfolio host. Convert image paths to absolute URLs (for example raw.githubusercontent.com) before rendering, so the embedded output points at a real location.
Theme is dark — clashes with a light portfolio
By designThe tool always links the dark Primer build. On a light site the dark surfaces look out of place. Swap the <link> to the github-markdown-light build and lighten the inline background, or use md-to-html for a more neutral self-contained doc.
Code blocks are not colour-highlighted
ExpectedFenced blocks carry a language-xxx class but no highlighter runs, so code is monospaced and boxed, not coloured. To add colour on your portfolio, load highlight.js or Prism on the page and let it pick up the class.
GitHub alert callouts degrade to text
Not supported[!NOTE] / [!TIP] show as literal text. Do not rely on them for emphasis in a featured doc — use bold or a heading, which render portably.
Footnotes and math do not render
Not supportedmarked default has no footnotes or math. [^1] breaks and $x$ prints literally. For a portfolio piece, inline footnote content and use an image for any equation.
Doc exceeds the character cap
rejectedFree tier caps at 500,000 characters / 1 MB. A very long write-up may be rejected. Pro raises it to 5,000,000 / 10 MB. Most single docs are well within free limits.
Trying to render several docs into one page
rejectedOne file per run. To feature a multi-part write-up as a single page, combine the parts with md-merger first, then render the merged file.
HTML in your Markdown passes through
Preservedmarked passes raw HTML in the source through to the output. That is convenient for custom embeds but means any unsanitised HTML in your doc ends up on your page — review it, since you control the portfolio's trust boundary.
Frequently asked questions
Will the GitHub styling clash with my portfolio's CSS?
Primer scopes its rules to .markdown-body, so as long as you keep the rendered content inside a class="markdown-body" wrapper, the styling stays contained and will not bleed into the rest of your page.
Is the output self-contained?
Not by default — the Primer CSS is a CDN <link>, not inlined. To embed the body, add that <link> to your page head or inline the stylesheet. For an automatically self-contained file, render with md-to-html instead.
Is the dark theme optional?
Not in the tool — it always links the dark Primer build. For a light portfolio, swap the downloaded file's <link> to the github-markdown-light build and lighten the inline background colours.
Do I need to credit github-markdown-css?
github-markdown-css is MIT-licensed. Including the original LICENSE text where you redistribute the CSS is good practice, though attribution in casual portfolio use is generally not strictly required. Check the license terms for your situation.
Why are my images broken on the live site?
Relative paths like ./img.png resolved in the repo but not on your portfolio host. Convert image references to absolute URLs (such as raw.githubusercontent.com) before rendering, so the embedded HTML points at a reachable location.
Can I get syntax-highlighted code on my portfolio?
The output adds a language-xxx class but does not colour the code itself. Load highlight.js or Prism on your portfolio page and it will highlight blocks using that class.
Is my draft doc uploaded anywhere?
No. Conversion runs entirely in your browser, so unpublished write-ups stay on your machine. If a doc references internal systems or keys, run md-secret-redactor before embedding it publicly.
What input does it take?
.md, .mdx, .markdown, .txt, or pasted text — one file per run. Multiple files are not accepted; merge with md-merger if needed.
Will raw HTML in my Markdown survive?
Yes — marked passes raw HTML through. That lets you include custom embeds, but review the source since whatever HTML is in your doc ends up on your page.
What are the size limits?
Free: 1 MB / 500,000 chars / 1 file. Pro: 10 MB / 5,000,000 / 10. Pro-media: 50 MB / 20,000,000 / 50. Developer: 500 MB / unlimited. Most portfolio docs fit comfortably in free.
Can I turn the doc into a PDF for a downloadable resume-style artifact?
Yes — use md-to-pdf-modern for a clean PDF or md-to-pdf-academic for a serif report look. This tool only emits HTML.
Can I convert an existing HTML write-up back to Markdown to feature it?
Yes — html-to-md converts HTML to clean Markdown via Turndown, which you can then render here for consistent GitHub styling.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.