Skip to main content
I wanted to add my awesome-tech-writing-skills repository to this portfolio, but with one hard constraint: the Mintlify page should not become a copied snapshot of the GitHub README. That constraint matters. A copied README looks fine on day one, but it quietly creates two sources of truth. The GitHub repository becomes the real project, while the portfolio page becomes a stale mirror that someone has to remember to update. For a curated resource list, stale content is a product bug. If the list changes on GitHub, the portfolio should reflect that change automatically.

​
The constraint

The simple options all had tradeoffs:
  1. Copy the README into this docs repo: Easy to render, but it duplicates content.
  2. Add the external repo as a Git submodule: Better than copying, but the submodule still pins a commit. It only updates when this repo updates the pointer.
  3. Fetch the raw GitHub file at runtime: Keeps one source of truth, but requires a renderer that can handle the Markdown patterns used by the source file.
I chose the third option. The Mintlify page now contains only a small wrapper: 
<RemoteReadme
  rawUrl="https://raw.githubusercontent.com/subin23k/awesome-tech-writing-skills/main/readme.md"
  repositoryUrl="https://github.com/subin23k/awesome-tech-writing-skills"
/>
The actual README remains in GitHub. Mintlify fetches it when the page loads.

​
What the renderer handles

The first version rendered the basic README well enough: headings, paragraphs, links, blockquotes, and unordered lists. Then the skill files exposed the edge cases:
  • YAML frontmatter should not appear on the page.
  • The first # heading should be skipped to avoid duplicating the Mintlify page title.
  • Wrapped list lines should stay inside the same bullet.
  • Fenced code blocks should render as code, not as stray backticks.
  • Numbered lists should remain ordered, even when the source Markdown contains nested bullets.
  • Nested bullets inside numbered steps should stay nested.
Those details are easy to miss because GitHub’s Markdown renderer handles them automatically. A small custom renderer has to be explicit about them.

​
Why not use a full Markdown parser?

A full Markdown parser is a library that understands Markdown broadly and converts it into HTML or React components correctly. Examples include remark, rehype, markdown-it, and marked. That kind of parser handles far more than the basics: tables, deeply nested lists, images, escaped characters, inline HTML, GitHub-flavored Markdown, task lists, footnotes, and a long tail of syntax edge cases. For a larger integration, I would reach for one of those libraries. In this case, the content surface is intentionally narrow: one README and three SKILL.md files from a repository I control. That made a small renderer acceptable because the supported Markdown patterns are known:
  • Headings
  • Paragraphs
  • Links and inline code
  • Blockquotes
  • Unordered and ordered lists
  • One nested unordered-list level
  • Fenced code blocks
  • YAML frontmatter stripping

​
The portfolio result

The portfolio now has a dedicated Tech Writing Skills tab with live-rendered pages for: Each page points to the GitHub source in its description and renders the latest remote file without committing a duplicate copy into this Mintlify repo.

​
The useful pattern

This pattern works when you want a portfolio, docs site, or internal portal to showcase external Markdown while preserving the upstream repository as the source of truth. The key decisions are:
  1. Keep the external file canonical.
  2. Render it where readers already are.
  3. Rewrite relative links back to the source repository.
  4. Treat formatting bugs as parser gaps, not content problems.
  5. Validate navigation and links after every wiring change.
The result is a cleaner maintenance model: GitHub remains where the resource is curated, and Mintlify becomes a live presentation layer instead of a second content store.

View the live-rendered resource

Open the Tech Writing Skills section and compare it with the GitHub source.