Implement blog system with markdown loader #42

New Issue

lmiranda · 2026-01-15T19:38:27Z

lmiranda commented

2026-01-15 19:38:27 +00:00

Description

Create a blog system using markdown files with frontmatter metadata. Includes a listing page, dynamic article routing, and a markdown processing utility.

Architecture

portfolio_app/
├── content/
│   └── blog/
│       ├── 2025-01-building-data-platform-team-of-one.md
│       ├── 2025-01-dbt-patterns-without-dbt.md
│       └── 2025-01-toronto-housing-postmortem.md
├── pages/
│   └── blog/
│       ├── __init__.py
│       ├── index.py          # Blog listing -> /blog
│       └── article.py        # Dynamic article -> /blog/<slug>
└── utils/
    └── markdown_loader.py    # Frontmatter parsing + rendering

Component Details

1. Markdown Loader (`utils/markdown_loader.py`)

def load_article(slug: str) -> dict:
    """Load and parse a markdown article by slug."""
    # Returns: {title, date, tags, excerpt, content_html}

def list_articles() -> list[dict]:
    """List all articles sorted by date descending."""
    # Returns: [{slug, title, date, tags, excerpt}, ...]

2. Blog Index Page (`pages/blog/index.py`)

Lists all articles as cards
Shows title, date, excerpt, tags
Links to individual article pages

3. Article Page (`pages/blog/article.py`)

Dynamic routing: path_template="/blog/<slug>"
Renders markdown content as HTML
Shows metadata (date, tags, reading time)
Navigation to previous/next articles

4. Frontmatter Format

---
title: "Building a Data Platform as a Team of One"
slug: building-data-platform-team-of-one
date: 2025-01-15
tags: [data-engineering, career, lessons-learned]
excerpt: "What I learned from 5 years as the sole data professional..."
---

Article content here...

Acceptance Criteria

content/blog/ directory created
markdown_loader.py utility implemented
Blog index page at /blog listing all articles
Dynamic article page at /blog/<slug>
Frontmatter parsing works (title, date, tags, excerpt)
Markdown renders to HTML correctly
Code blocks have syntax highlighting
2-3 placeholder articles created (can be lorem ipsum or outlines from blueprint)
Tags displayed as badges
Date formatted consistently
Mobile responsive layout
Theme-aware styling (dark/light code blocks)

Dependencies

Add to pyproject.toml: python-frontmatter, markdown, pygments (for syntax highlighting)
Depends on: #40 (Extend sidebar navigation)

Initial Articles (Placeholders)

From blueprint "5. BLOG PAGE":

"Building a Data Platform as a Team of One"
"dbt Patterns Without dbt"
"The Toronto Housing Market Dashboard: A Postmortem"

Content can be placeholder text with the article structure from the blueprint.

Technical Notes

Use dash.register_page() with path_template for dynamic routing
Consider dmc.TypographyStylesProvider for markdown HTML styling
Use html.Div(dangerously_allow_html=True) carefully for rendered markdown
Implement caching for markdown parsing (articles don't change often)

Labels: Type/Feature, Priority/High, Complexity/High, Efforts/L, Component/Frontend, Tech/Python, Sprint/8

## Description Create a blog system using markdown files with frontmatter metadata. Includes a listing page, dynamic article routing, and a markdown processing utility. ## Architecture ``` portfolio_app/ ├── content/ │ └── blog/ │ ├── 2025-01-building-data-platform-team-of-one.md │ ├── 2025-01-dbt-patterns-without-dbt.md │ └── 2025-01-toronto-housing-postmortem.md ├── pages/ │ └── blog/ │ ├── __init__.py │ ├── index.py # Blog listing -> /blog │ └── article.py # Dynamic article -> /blog/<slug> └── utils/ └── markdown_loader.py # Frontmatter parsing + rendering ``` ## Component Details ### 1. Markdown Loader (`utils/markdown_loader.py`) ```python def load_article(slug: str) -> dict: """Load and parse a markdown article by slug.""" # Returns: {title, date, tags, excerpt, content_html} def list_articles() -> list[dict]: """List all articles sorted by date descending.""" # Returns: [{slug, title, date, tags, excerpt}, ...] ``` ### 2. Blog Index Page (`pages/blog/index.py`) - Lists all articles as cards - Shows title, date, excerpt, tags - Links to individual article pages ### 3. Article Page (`pages/blog/article.py`) - Dynamic routing: `path_template="/blog/<slug>"` - Renders markdown content as HTML - Shows metadata (date, tags, reading time) - Navigation to previous/next articles ### 4. Frontmatter Format ```markdown --- title: "Building a Data Platform as a Team of One" slug: building-data-platform-team-of-one date: 2025-01-15 tags: [data-engineering, career, lessons-learned] excerpt: "What I learned from 5 years as the sole data professional..." --- Article content here... ``` ## Acceptance Criteria - [ ] `content/blog/` directory created - [ ] `markdown_loader.py` utility implemented - [ ] Blog index page at `/blog` listing all articles - [ ] Dynamic article page at `/blog/<slug>` - [ ] Frontmatter parsing works (title, date, tags, excerpt) - [ ] Markdown renders to HTML correctly - [ ] Code blocks have syntax highlighting - [ ] 2-3 placeholder articles created (can be lorem ipsum or outlines from blueprint) - [ ] Tags displayed as badges - [ ] Date formatted consistently - [ ] Mobile responsive layout - [ ] Theme-aware styling (dark/light code blocks) ## Dependencies - Add to `pyproject.toml`: `python-frontmatter`, `markdown`, `pygments` (for syntax highlighting) - Depends on: #40 (Extend sidebar navigation) ## Initial Articles (Placeholders) From blueprint "5. BLOG PAGE": 1. "Building a Data Platform as a Team of One" 2. "dbt Patterns Without dbt" 3. "The Toronto Housing Market Dashboard: A Postmortem" Content can be placeholder text with the article structure from the blueprint. ## Technical Notes - Use `dash.register_page()` with `path_template` for dynamic routing - Consider `dmc.TypographyStylesProvider` for markdown HTML styling - Use `html.Div(dangerously_allow_html=True)` carefully for rendered markdown - Implement caching for markdown parsing (articles don't change often) --- **Labels:** Type/Feature, Priority/High, Complexity/High, Efforts/L, Component/Frontend, Tech/Python, Sprint/8

lmiranda referenced this issue

2026-01-15 19:38:50 +00:00

Add blog dependencies to pyproject.toml #43

lmiranda commented

2026-01-15 20:08:52 +00:00

✅ Completed

Implemented full blog system with markdown + frontmatter:

Files Created:

portfolio_app/utils/markdown_loader.py - Markdown parsing with syntax highlighting
portfolio_app/pages/blog/index.py - Article listing at /blog
portfolio_app/pages/blog/article.py - Dynamic routing at /blog/<slug>
portfolio_app/content/blog/building-data-platform-team-of-one.md - First article

Features:

YAML frontmatter for metadata (title, date, description, tags, status)
Syntax highlighting via Pygments
Draft/published status filtering
Empty state when no articles
404 handling for missing articles

All syntax and lint checks pass. Markdown loader tested and working.

✅ **Completed** Implemented full blog system with markdown + frontmatter: **Files Created:** - `portfolio_app/utils/markdown_loader.py` - Markdown parsing with syntax highlighting - `portfolio_app/pages/blog/index.py` - Article listing at `/blog` - `portfolio_app/pages/blog/article.py` - Dynamic routing at `/blog/<slug>` - `portfolio_app/content/blog/building-data-platform-team-of-one.md` - First article **Features:** - YAML frontmatter for metadata (title, date, description, tags, status) - Syntax highlighting via Pygments - Draft/published status filtering - Empty state when no articles - 404 handling for missing articles All syntax and lint checks pass. Markdown loader tested and working.

lmiranda closed this issue

2026-01-15 20:08:52 +00:00

lmiranda referenced this issue from a commit

2026-01-15 20:40:22 +00:00

feat: Implement Sprint 8 - Portfolio website expansion (MVP)

lmiranda referenced this issue

2026-01-15 20:46:49 +00:00

feat: Implement Sprint 8 - Portfolio website expansion (MVP) #45

lmiranda added this to the Launch: Host, Bio and Toronto House Market Analysis project 2026-01-16 14:51:54 +00:00

lmiranda self-assigned this 2026-01-16 14:51:59 +00:00

lmiranda moved this to Done in Launch: Host, Bio and Toronto House Market Analysis on 2026-01-16 14:52:31 +00:00

Sign in to join this conversation.