Hugo Markdown Skill

Create and edit Hugo-compatible markdown that works seamlessly with the existing Hugo + Obsidian workflow. This skill covers Hugo-specific extensions and the conversion between Obsidian and Hugo formats.

Workflow: Creating a Hugo Post

  1. Add TOML frontmatter with title, date, tags, and draft status at the top of the file
  2. Write content using standard Markdown for structure, plus Hugo-specific syntax below
  3. Link related notes using Hugo wikilink shortcodes ( Note) for internal vault connections
  4. Add Hugo shortcodes for enhanced functionality (alerts, figures, etc.)
  5. Test locally with hugo server to verify the post renders correctly
  6. Deploy via GitHub Actions pipeline when ready

When choosing between wikilink shortcodes and standard links: use note for notes within the vault (maintains Obsidian compatibility) and [text](url) for external URLs only.

TOML Frontmatter

Hugo uses TOML frontmatter delimited by +++:

+++
title = "My Blog Post"
date = "2024-01-15T10:30:00"
tags = ["blogging", "hugo", "static-sites"]
draft = false
+++

Required fields:

  • title - Post title (quoted string)
  • date - Publication date (ISO format recommended)
  • draft - Boolean (false for published, true for drafts)

Optional fields:

  • tags - Array of tag strings
  • description - Meta description for SEO
  • author - Author name
  • categories - Higher-level groupings than tags

Template for new posts:

+++
title = "{{title}}"
date = "{{date:YYYY-MM-DD}}T{{time:HH:mm:ss}}"
tags = ["nota"]
draft = false
+++

# {{title}}

Write your content here.

Instead of Obsidian wikilinks, use Hugo shortcodes:


  Note Name                    Link to note

  Display Text     Custom display text

  Note Name#section            Link to heading (if supported)

These shortcodes:

  • Maintain compatibility with Obsidian when viewed in the vault
  • Get processed by Hugo during build
  • Can be converted automatically by obsidian-to-hugo.py script

Hugo Shortcodes

Hugo provides built-in shortcodes for enhanced functionality:

Figures and Images


            
Caption

        





Caption

            
Caption

YouTube Videos

Gists

Highlight Code

def hello():
    print("Hello, Hugo!")

Math Support

If hugo-bearblog theme supports math, use standard LaTeX:

Inline: $e^{i\pi} + 1 = 0$

Block:
$$
\frac{a}{b} = c
$$

Content Organization

Directory Structure

content/
├── Postagens/          # Main blog posts
│   └── my-post/
│       └── index.md
├── Portfólio/          # Portfolio items
├── notas/              # Obsidian notes (imported)
└── _index.md           # Homepage

Post Structure

Each blog post should be in its own subdirectory with an index.md file:

content/Postagens/my-great-post/
├── index.md            # Main content
├── image1.jpg          # Post assets
└── diagram.png

This structure allows:

  • Bundled resources (images, files) with posts
  • Clean URLs (/postagens/my-great-post/)
  • Easy asset management

Conversion from Obsidian

Manual Conversion Process

  1. Copy note from Obsidian vault to content/notas/
  2. Convert frontmatter from YAML (---) to TOML (+++)
  3. Replace wikilinks with shortcodes using regex:
    • Note Title → Note Title
    • Display → Display
  4. Clean metadata (remove Obsidian-specific comments)
  5. Test locally with hugo server

Automated Conversion

Use the vault-importer.py script:

# Preview conversions
python3 scripts/vault-importer.py --dry-run

# Convert all files from importando-vaults to notas
python3 scripts/vault-importer.py

The script automatically:

  • Detects note patterns (YAML, pseudo-YAML, diary, mixed)
  • Converts frontmatter to TOML
  • Simplifies complex wikilinks
  • Extracts and cleans tags
  • Applies consistent formatting

Publishing Workflow

Local Development

hugo server          # Start dev server
hugo server -D       # Include drafts

Deployment

  1. Push to main branch - triggers GitHub Actions
  2. Automatic build - Hugo processes all content
  3. Wikilink conversion - obsidian-to-hugo.py runs
  4. Deploy to GitHub Pages - via pages.yml workflow

Theme-Specific Features (hugo-bearblog)

Minimal Design

  • Focus on content over aesthetics
  • Fast loading (no JavaScript by default)
  • Clean typography

Configuration

Key settings in config.toml:

[params]
  title = "Blog Title"
  description = "Blog description"
  # Hide "made with" line
  hideMadeWith = true

Portuguese Support

languageCode = "pt-BR"

Complete Example

+++
title = "Reflexões sobre Static Site Generators"
date = "2024-01-15T09:00:00"
tags = ["web", "hugo", "jamstack", "reflexão"]
draft = false
+++

# Reflexões sobre Static Site Generators

Depois de migrar de 
  WordPress para Hugo, algumas observações sobre o processo.

## Vantagens Descobertas

- **Performance**: Sites estáticos são naturalmente rápidos
- **Segurança**: Sem banco de dados, sem vulnerabilidades comuns
- **Versionamento**: Todo conteúdo no Git

## Integração com Obsidian

A combinação Hugo + 
  Obsidian permite:

1. Escrever em ambiente familiar
2. Manter links internos funcionais
3. Publicar automaticamente

Ver também: 
  meu workflow atual

## Próximos Passos

- Explorar 
  Hugo Modules
- Implementar 
  busca no site
- Melhorar 
  SEO

Troubleshooting

Common Issues

Wikilinks not converting: Check that obsidian-to-hugo.py is running in the GitHub Actions workflow.

TOML syntax errors: Ensure all strings are properly quoted, especially titles with special characters.

Build failures: Check Hugo version compatibility and verify all shortcodes are properly closed.

Missing assets: Ensure images and files are in the correct bundle directory structure.

Validation

Local testing:

hugo server --navigateToChanged  # Auto-refresh on changes

Build testing:

hugo --minify                    # Production build

Link checking: Manually verify wikilinks resolve correctly in the built site.

References