Skip to main content

Skill Guide

Markdown, HTML, and platform-native formatting standards

The mastery of lightweight markup syntax (Markdown), semantic document structuring (HTML), and adherence to the specific content formatting rules of digital platforms (e.g., GitHub, Atlassian, Slack) to create clear, consistent, and platform-optimized technical documentation and communication.

This skill directly reduces technical debt in documentation and communication, accelerating onboarding, debugging, and cross-team collaboration. It ensures information is consistently structured, searchable, and maintainable across an organization's entire digital knowledge ecosystem.
1 Careers
1 Categories
8.7 Avg Demand
22% Avg AI Risk

How to Learn Markdown, HTML, and platform-native formatting standards

1. **Markdown Syntax Core:** Master the essentials: headers (`#`, `##`), bold/italic (`**bold**`), lists, code blocks (triple backticks), and links. Use the [CommonMark Spec](https://spec.commonmark.org/) as the source of truth. 2. **Semantic HTML Fundamentals:** Understand the purpose of tags like `

`, `

`, `

    `, ``, and ``. Focus on *meaning* over visual presentation. 3. **Platform Paradox:** Learn that `#` means a header in a README.md, but is a hyperlink anchor in a Jira description. Identify the 3-5 platforms your team uses daily.

1. **Platform-Specific Parsing:** Go beyond basic syntax. Learn GitHub Flavored Markdown (GFM) extensions like task lists (`- [x]`) and tables, Atlassian Wiki Markup for Confluence/Jira, and Markdown dialects for Slack/Discord. 2. **Toolchain Integration:** Use linters (e.g., `markdownlint`) and formatters in your CI/CD pipeline to enforce style guides automatically. 3. **Common Mistake:** Overusing raw HTML in Markdown for layout. This breaks portability and semantic clarity. Use platform-native elements instead.
1. **Systems Architecture:** Design and enforce organization-wide content standards. Create a living style guide (in Markdown/HTML) that defines when to use which format (e.g., Markdown for READMEs, HTML for complex email templates, native markup for ticket updates). 2. **Automation & Templating:** Develop reusable templates and snippets for common document types (e.g., RFCs, post-mortems, ADRs) using tools like Docusaurus or MkDocs. 3. **Mentorship:** Conduct code reviews focused *only* on documentation quality and consistency, treating it as a first-class artifact.

Practice Projects

Beginner
Project

Create a Multi-Platform README for a Personal Project

Scenario

You have a simple Python script on GitHub. You need to create a README that is clear on GitHub, but also looks good when the raw Markdown is pasted into a Jira ticket or Slack message.

How to Execute
1. Write the README in standard Markdown (`.md`). 2. Use GFM-specific features like a task list for setup steps. 3. Test its render on GitHub. 4. Copy the raw content and paste it into a new Jira ticket and a Slack message. Document any rendering failures (e.g., GFM tables not rendering in Jira) in the README itself as a note.
Intermediate
Project

Build and Deploy a Documentation Site with Docusaurus

Scenario

Your team's internal API documentation is scattered across Google Docs and random wiki pages. You need to consolidate it into a single, searchable, version-controlled site.

How to Execute
1. Initialize a Docusaurus project. 2. Migrate three key API docs from Google Docs to Markdown, using proper frontmatter for metadata. 3. Set up a basic sidebar navigation structure in `docusaurus.config.js`. 4. Write a GitHub Action that builds and deploys the site to GitHub Pages on merge to `main`. 5. Present the site to your team, highlighting the search functionality.
Advanced
Project

Implement an Automated Documentation Quality Gate

Scenario

As a Tech Lead, you notice documentation quality is inconsistent. You want to enforce style and structural rules on all Markdown and HTML content in the repository automatically.

How to Execute
1. Integrate `markdownlint` with a custom `.markdownlint.json` rule set into the project's pre-commit hooks and CI pipeline. 2. Create a custom linting rule (or use a pre-existing one) to check for the presence of required sections (e.g., '## Dependencies') in all new Markdown files. 3. Configure the CI job to fail the build if any linting rule is violated, providing actionable error messages. 4. Write a short internal guide on 'How to Fix Common Linting Errors'.

Tools & Frameworks

Software & Platforms

MarkdownlintPrettier (with MDX support)Docusaurus/MkDocsGitHub Flavored Markdown SpecAtlassian Wiki Markup

Use **markdownlint** and **Prettier** in local editors and CI/CD for automated formatting and style enforcement. Use **Docusaurus** or **MkDocs** for building structured, multi-page documentation sites from Markdown files. Always reference the platform's official spec (GFM, Atlassian) for edge-case syntax.

Mental Models & Methodologies

Diátaxis Documentation FrameworkContent-as-Code ParadigmSemantic HTML Principle

Apply the **Diátaxis** framework (tutorials, how-tos, reference, explanation) to structure your documentation types logically. Adopt **Content-as-Code** by treating all documentation with the same rigor as source code (version control, review, automated testing). Use **Semantic HTML** to ensure content is accessible and machine-readable, even when you're writing in Markdown.

Interview Questions

Answer Strategy

The interviewer is testing for practical, platform-aware quality standards. Strategy: Demonstrate a systematic checklist and specific, actionable feedback. **Sample Answer:** 'First, I'd check the render in Jira's preview. Then, I'd verify: 1) All code samples are in fenced code blocks (triple backticks) for syntax highlighting, not indented spaces. 2) Nested lists use consistent indentation (2 or 4 spaces) and are parseable. 3) Hyperlinks are valid and use absolute URLs, not relative paths. My feedback would be: "The render looks good, but let's fix the code blocks to use ``` for proper highlighting in Jira. Also, change the relative link `/api/auth` to the full `https://...` to ensure it works from the ticket context."'

Answer Strategy

Testing strategic decision-making based on audience, maintenance, and workflow. Strategy: Frame the answer around the **Content-as-Code** paradigm and user workflow. **Sample Answer:** 'For a critical runbook, **version control and auditability are paramount**. I would use **Markdown in a Git repo**. The trade-off is a slightly higher barrier to edit for non-technical stakeholders, but the gain is a single source of truth, a full history of changes via `git log`, and the ability to include runbook updates in the same PR as infrastructure-as-code changes. I would *not* use a Confluence wiki for this because it exists outside the deployment pipeline and lacks granular version control. HTML in a portal is a read-only rendering target, not a authoring format.'

Careers That Require Markdown, HTML, and platform-native formatting standards

1 career found