Which Markup Is Better if You Are a Writer Who Contributes and Publishes Content on GitHub
If you’re a writer hosting your portfolio, tutorials, and writing samples on GitHub, the choice between Markdown and HTML depends on your goals, workflow, and audience. Let’s look at their advantages and disadvantages to help you make the best choice:
Markdown
✅ Pros
Native to GitHub → GitHub automatically renders .md files beautifully. Your README, portfolio pages, and tutorials will look clean without extra effort.
Lightweight & simple → Easier and faster to write than HTML.
Readable in raw form → Even if someone views your repo as plain text, Markdown looks clean.
Supports extensions → GitHub Flavored Markdown (GFM) adds tables, task lists, code syntax highlighting, footnotes, etc. — great for tutorials.
Note: GitHub Flavored Markdown (GFM) should not confuse you. It’s just another version of Markdown that supports extra features beyond the regular syntax you use in formatting text — e.g., tables, task lists (- [ ]), automatic URL linking, and syntax highlighting for code blocks.
The good news is you don’t need to activate it — it’s already enabled by default on GitHub. The only thing you need to do is learn and apply the new syntax and features it provides.
- Portable → You can convert .md into HTML, PDF, DOCX, etc., with tools like Pandoc if you need polished documents later.
⚠️ Cons
Limited styling → Custom layouts, interactive elements, or advanced formatting require HTML/CSS. Switch to HTML for advanced formatting.
Less control → You can’t design the page beyond GitHub’s rendering rules.
HTML
✅ Pros
Full control → Lets you customize typography, structure, layout, and interactivity.
Web-ready → You can host HTML files on GitHub Pages for a polished, website-like portfolio.
Scalable → Easier to integrate custom CSS/JS if you want your portfolio to look like a professional website rather than just repo docs.
⚠️ Cons
Heavier to write → Writing tutorials in raw HTML is tedious compared to Markdown.
Cluttered raw view → If someone browses your repo directly, HTML isn’t as readable as Markdown.
Overhead → Requires more effort to maintain consistency across documents.
Best Approach for a Technical Writer
👉 Use Markdown for your writing samples, tutorials, and documentation because:
It’s the industry standard for technical writing in open-source, docs, and GitHub.
It showcases your ability to write developer-friendly, accessible content.
It’s future-proof and easy to export.
👉 Use HTML (with GitHub Pages) for your portfolio site itself, because:
A portfolio benefits from visual polish (navigation, layout, branding).
You can link out to .md tutorials and samples directly in a styled site.
🔑 Recommendation
Write tutorials and samples in Markdown (.md) to demonstrate technical writing skills.
Build a portfolio landing page in HTML (or Jekyll/GitHub Pages with Markdown) for presentation.
That way, you show both clarity in technical documentation and professional presentation skills.
Top comments (0)