woosal1337/blog: Dark editorial personal blog template built on Next.js
A dark editorial personal-blog template built with Next.js 14 and MDX, featuring reusable design primitives, deterministic title-based banners and a Tailwind token layer—designed for front-end developers and creators to quickly launch a customizable portfolio and writing site.
GitHub woosal1337/blog Updated 2026-08-06 Branch main Stars 399 Forks 32
Next.js 14 React TypeScript MDX Tailwind CSS Bun Biome Personal Blog Portfolio Editorial Typography

💡 Deep Analysis

4
Why choose Next.js 14 App Router + MDX colocated, and what are the advantages for content development and maintenance?

Core Analysis

Question Focus: Choosing Next.js 14 App Router with colocated MDX aims to keep content (MDX) closely coupled with page and component logic to improve developer efficiency, composability, and maintainability.

Technical Features & Benefits

  • Directory-as-route: Each MDX sits next to its layout and page logic, reducing discovery and context mismatch.
  • Componentized writing: MDX can import primitives from components/ds/, enabling reusable interactive elements (callouts, TOC markers, per-post chrome) inside content.
  • Unified metadata & layout: Managing metadata, styles, and routing behavior in the same folder simplifies localized style changes and experimentation.
  • Build optimization friendly: Next.js SSG/ISR workflows align well with colocated content when the host supports App Router.

Usage Recommendations

  1. Structured authoring: Reuse components/ds/ inside MDX rather than embedding lots of styling classes in content.
  2. Migration planning: If moving from pages/, prepare a checklist for layout and metadata changes and redirects.
  3. Test per-post chrome: Verify TOC and per-post UI across articles of different lengths and structures.

Caveats

  • Learning curve: Developers unfamiliar with the App Router must adapt to new colocated and nested layout semantics.
  • Not a CMS: Content resides in the repo, ideal for developer-centric workflows, not for frequent non-technical editorial updates.

Important Notice: App Router + colocated MDX is an efficient choice for control and componentized writing. For visual editing or multi-editor workflows, pair with an external CMS.

Summary: This architecture tightly couples content and UI, giving authors fine-grained control and consistent layout, at the cost of learning the App Router conventions.

88.0%
What is the local development and tooling experience like? Common issues and best practices?

Core Analysis

Question Focus: The project defaults to Bun and Biome, offering faster local iterations and integrated lint/format but introducing compatibility and onboarding costs.

Technical Analysis (UX points)

  • Benefits:
  • bun install and bun dev are typically faster than npm/PNPM, yielding quicker feedback loops.
  • Biome combines linting and formatting; bun run check can auto-fix issues.
  • Common issues:
  • Requires Node >= 20 and Bun; missing either causes install/run failures.
  • Editors like VSCode may not have Biome support out-of-the-box, needing plugins or config.
  • Some npm packages or scripts can behave differently under Bun vs Node/npm.

Best Practices

  1. Pin environment: Use the same Node and Bun versions locally and in CI (via Volta/nvm + bun installation scripts or fixed CI images).
  2. Editor config: Add Biome plugin or wire editor.formatOnSave to run Biome/bun check in workspace settings.
  3. Dependency validation: After first install, run build/check to catch Bun-specific incompatibilities.
  4. Document commands: Clearly list bun dev, bun run build, bun run check in CONTRIBUTING/README to reduce onboarding friction.

Caveats

  • If your team or CI cannot adopt Bun, consider migrating to Node/npm workflows but factor in the effort to replace Biome and adjust scripts.

Important Notice: Adopting Bun and Biome requires synchronizing tool versions across team and CI; otherwise environment inconsistencies will cause repeated issues.

Summary: The toolchain improves speed and consistency but requires explicit version and editor integration to avoid common pitfalls.

87.0%
If I want to heavily customize styles or extend the component system, what best practices and change priorities should I follow?

Core Analysis

Question Focus: For heavy style customization or component system extension, follow a prioritized, layered approach to avoid style fragmentation and rising maintenance costs.

Technical Analysis (Priorities & Principles)

  • Token-first: Begin by updating base tokens in app/globals.css (colors, spacing, typography, motion) because components reference these values.
  • Componentized extension: Add/extend primitives in components/ds/ with size, variant, or theme props, ensuring they reference tokens rather than hard-coded styles.
  • Blocks & page layer: Extend components/blocks/ to compose primitives into page structures; blocks should not directly mutate tokens.
  • MDX conventions: Encourage component reuse in MDX rather than embedding many utility classes to keep content semantic.

Practical Steps (Implementation Plan)

  1. Audit: Identify all tokens and components that will be affected.
  2. Layered changes: Modify tokens -> update core primitives -> run site-wide checks and manual review -> adjust blocks -> fix MDX content as needed.
  3. Visual regression / review: For large changes, use screenshot diffing or manual review on key pages (home, posts, banners).
  4. Sync contour/branding: If tokens affecting brand (primary color, stroke) change, update lib/contour.ts parameters to maintain identity coherence.

Caveats

  • Avoid per-article overrides of tokens except for deliberate, documented exceptions.
  • Match the existing API style when extending components and include MDX usage examples.

Important Notice: Centralized token changes followed by layered propagation minimizes rollback risk and style fragmentation.

Summary: A token-first, component-first, layered workflow with visual regression ensures large-scale customization stays maintainable while preserving visual consistency.

87.0%
How does the programmatic contour (cover) work, and can I replace or extend it to match my brand?

Core Analysis

Question Focus: lib/contour.ts acts as the single source of truth for visual identity — programmatically generating contour-based assets for covers, logo, and favicon. Understanding its inputs and outputs is key to customizing brand appearance.

Technical Analysis

  • Likely implementation: Located under lib/, described as deterministic — inputs (e.g., title or seed) are mapped via an algorithm to geometry or SVG outputs and scaled into multiple variants.
  • Advantages: Ensures consistent visuals across assets; automates asset creation; integrates well with build-time generation for manifests and social previews.
  • Limitations: Programmatic output may not match highly bespoke or photographic branding needs.

Practical Recommendations (extend or replace)

  1. Preferred — Parameterized tweaks: Inspect lib/contour.ts for parameters (color, stroke, complexity, seed) and expose them via tokens (app/globals.css) so brand changes remain centralized.
  2. Alternative — Pluggable replacement: If you need a completely different style, swap in a custom generator or static SVGs and update build/manifest logic to use the new assets (remember to cover favicon and social preview sizes).
  3. Hybrid approach: Use manual covers for key posts while keeping contour as the default to retain automation benefits.

Caveats

  • Full replacement increases maintenance: ensure all asset variants and sizes are covered.
  • If generation happens in CI, confirm Bun and your deployment pipeline support required image operations.

Important Notice: Start with parameterized changes to lib/contour.ts; replace only when truly necessary and ensure full asset pipeline alignment.

Summary: The contour system provides low-maintenance, consistent identity. Customize via parameters first; replace only if you need drastically different branding, and then update the whole asset generation chain accordingly.

86.0%

✨ Highlights

  • Dark, editorial-styled personal site and typography
  • MDX-based posts with a left-rail table of contents
  • Deterministic title-based post banners and a single contour identity mark
  • Runtime depends on Bun and Node >=20, which imposes compatibility constraints

🔧 Engineering

  • Built with Next.js 14, MDX and TypeScript, emphasizing reusable design-system primitives
  • Tailwind token layer and dark theme with componentized domain blocks suitable for extension and customization

⚠️ Risks

  • Repository contributor count shows 0 and community size is small, creating uncertainty around maintenance and long-term support
  • Blog content and images are reserved while code is MIT: license boundaries should be verified before reuse

👥 For who?

  • Aimed at front-end developers, individual writers and creators focused on visual typography
  • Suitable for users wanting to quickly build a customizable personal blog or portfolio and who accept the Bun ecosystem