A bilingual static blog (Brazilian Portuguese + English) for publishing technical articles with co-located images. Powered by Hugo extended, themed with Congo, and hosted on GitHub Pages.
🌐 Live: https://luanmds.github.io
📦 Repository: github.com/luanmds/luanmds.github.io
- Hugo extended v0.154.5+ (required — Congo uses extended-only SCSS compilation)
- Docker + Docker Compose (for local development)
- Git with submodule support
Clone the repository with all submodules:
git clone --recurse-submodules https://github.com/luanmds/luanmds.github.io.git
cd luanmds.github.ioStart the local dev server:
docker compose upOpen http://localhost:1313 in your browser. Changes to content, layouts, or styles auto-reload.
Generate optimized static site:
hugo --minifyOutput goes to public/ directory.
Verify the build with Hugo extended in Docker:
docker run --rm -v $(pwd):/src -w /src hugomods/hugo:exts hugo --minify| Technology | Purpose |
|---|---|
| Hugo extended | ⚡ Static site generator — compiles Markdown + Go templates into HTML |
| Congo | 🎨 Active theme (Git submodule from jpanther/congo) |
| GitHub Pages | 🌍 Free static hosting |
| GitHub Actions | 🔄 CI/CD — automatic build and deploy on push to main |
| Fuse.js | 🔍 Client-side full-text search (native Congo integration) |
| Giscus | 💬 Comment system via GitHub Discussions (currently placeholder config) |
- 🌐 Bilingual Support — Two language versions (PT default on
/, EN on/en/) with language switching in header and article context switcher - 🌙 Dark Mode — Native dark/light theme toggle with system preference auto-detection
- 🔍 Client-Side Search — Full-text search via Fuse.js, no backend required
- 🏷️ Taxonomies — Tags (with dedicated page) and categories
- 📡 RSS Feeds — Separate feeds for each language
- 📦 Page Bundles — Articles organized as folders with co-located images and assets
- 📝 Markdown Authoring — All content written in Markdown with YAML front matter
- 📱 Responsive Design — Mobile-first layout via Congo theme
- 🔗 Breadcrumbs & Pagination — Navigation aids in articles
- 📅 Future-Dated Posts — Automatic handling of scheduled publications
Detailed documentation is in .docs/. Use this table to find what you need:
| Topic | File | Contains |
|---|---|---|
| 📝 Project identity, author, purpose | .docs/project.md |
What is the project, who built it, what problem it solves |
| 🛠️ Dependencies, versions, tools | .docs/stack.md |
Hugo version, theme, Docker setup, Fuse.js, Giscus |
| 🏗️ Architecture & design decisions | .docs/architecture.md |
SSG model, bilingual strategy, theme overrides, CI/CD design |
| 📋 Naming, commits, front matter | .docs/conventions.md |
Conventional Commits, slugs, article YAML fields, what to avoid |
| 📂 Folder structure & responsibilities | .docs/structure.md |
Purpose of every directory and subdirectory |
| ✅ Testing & validation strategy | .docs/testing.md |
Playwright skill usage, build-as-test, local validation process |
| 🔗 External services & integrations | .docs/integrations.md |
GitHub Pages, Actions, Giscus setup, CodeRabbit configuration |
.docs/concerns.md |
Congo upgrade fragility, Giscus placeholder status, design system gaps | |
| ✨ Complete feature inventory | .docs/features.md |
Everything that works: search, dark mode, tags, comments, etc. |
| ✍️ Article authoring guide | .docs/articles.md |
Page bundle format, front matter fields, image handling, pngquant rules |
- ⭐ Hugo extended is mandatory — Congo theme requires SCSS transpilation, which only works with extended version
- 🔒 Docker user permissions — Use
--user $(id -u):$(id -g)flag or fix file ownership afterwards (Docker creates files as root by default) - 📦 Git submodules — Update after clone:
git submodule update --init --recursive - 💬 Giscus comments — DISABLED FOR NOW — Currently uses placeholder config. To enable in the future: go to giscus.app, configure repo, and update
repoIdandcategoryIdinhugo.toml - 🔄 GitHub Actions — Uses
peaceiris/actions-hugo@v3withextended: truefor CI/CD
👤 Author: Luan Mello (Backend engineer, .NET specialist, distributed systems)
🌐 Live Blog: https://luanmds.github.io
📦 GitHub Repo: github.com/luanmds/luanmds.github.io
This project is open source. The blog content (articles in content/) is authored by Luan Mello. The template, configurations, and customizations are available for reference and adaptation.