Hugo Markdown Skill

Create and edit markdown for the walkerblog pipeline. Escreva sempre em sintaxe Obsidian — o CI converte automaticamente antes do build. Nunca use diretamente no source.

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
3. Link related notes using Obsidian wikilinks ([[Note Name]]) — o CI converte para shortcodes Hugo automaticamente
4. Add Hugo shortcodes para funcionalidades especiais (figures, youtube, etc.)
5. Deploy via git push → GitHub Actions pipeline

Use [[wikilinks]] para notas internas (o CI converte). Use [text](url) para URLs externas.

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.

Internal Links (Wikilink Shortcodes)

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

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
   • [[Note|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

• Hugo Documentation
• Hugo Shortcodes
• TOML Spec
• hugo-bearblog Theme