Hackmd

HackMD Skill

Overview

HackMD is a collaborative markdown platform that supports real-time editing, slide presentations, and embedded content. This skill covers best practices for creating HackMD-compatible documents, particularly with embedded SVG diagrams.

Slide Mode

HackMD supports presentation mode using --- separators between slides.

YAML Frontmatter

---
title: Presentation Title
tags: tag1, tag2
slideOptions:
  theme: white    # white, black, league, beige, sky, night, serif, simple, solarized
  transition: slide  # none, fade, slide, convex, concave, zoom
---

Slide Controls

• --- creates a new horizontal slide
• ---- creates a vertical slide (nested under previous)
• Press S for speaker view
• Press F for fullscreen
• Arrow keys to navigate

SVG Embedding Best Practices

✅ DO: Use Direct Coordinates

<rect x="120" y="95" width="120" height="50" rx="8" fill="#4285f4"/>
<text x="180" y="115" text-anchor="middle" fill="white">Label</text>

❌ DON'T: Use Transform Translate

<!-- This may not render correctly in HackMD -->
<g transform="translate(180, 120)">
  <rect x="-60" y="-25" width="120" height="50"/>
</g>

✅ DO: Use Simple Markers in Defs

<defs>
  <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
    <polygon points="0 0, 10 3.5, 0 7" fill="#666"/>
  </marker>
</defs>

❌ DON'T: Use Filters (Shadows, Blur, etc.)

<!-- These will NOT render in HackMD -->
<defs>
  <filter id="shadow">
    <feDropShadow dx="2" dy="2" stdDeviation="3"/>
  </filter>
</defs>
<rect filter="url(#shadow)"/>  <!-- Won't work -->

✅ DO: Use Unique IDs for Multiple SVGs

When embedding multiple SVGs in one document, use unique IDs to avoid conflicts:

<!-- First SVG -->
<marker id="arrow-slide1" ...>

<!-- Second SVG -->
<marker id="arrow-slide2" ...>

✅ DO: Use Inline Opacity

<g opacity="0.3">
  <rect .../>
  <text .../>
</g>

❌ DON'T: Use Complex CSS or External Stylesheets

<!-- Avoid -->
<style>
  .highlight { fill: blue; }
</style>

SVG Template for HackMD

<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" 
     style="font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif;">
  <defs>
    <marker id="arr" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#666"/>
    </marker>
  </defs>
  
  <!-- Background -->
  <rect x="0" y="0" width="800" height="400" fill="#f5f5f5"/>
  
  <!-- Boxes with direct coordinates -->
  <rect x="50" y="100" width="120" height="50" rx="8" fill="#4285f4" stroke="#1a73e8" stroke-width="2"/>
  <text x="110" y="130" text-anchor="middle" fill="white" font-size="12" font-weight="bold">Box 1</text>
  
  <!-- Arrows -->
  <path d="M 170 125 L 250 125" fill="none" stroke="#666" stroke-width="1.5" marker-end="url(#arr)"/>
  
  <!-- Dimmed elements -->
  <g opacity="0.3">
    <rect x="50" y="200" width="120" height="50" rx="8" fill="#4285f4"/>
    <text x="110" y="230" text-anchor="middle" fill="white" font-size="12">Inactive</text>
  </g>
</svg>

Common Issues and Solutions

Supported SVG Features

Mermaid Alternative

For simpler diagrams, HackMD natively supports Mermaid:

```mermaid
flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
```

When to use Mermaid vs SVG:

• Mermaid: Quick flowcharts, sequence diagrams, simple graphs
• SVG: Custom styling, complex layouts, precise positioning, branded colors

Export Options

From HackMD you can export to:

• PDF (from slide mode)
• HTML
• Markdown
• ODF

References

• HackMD Documentation
• HackMD Slide Mode