Skip to content

project-structure.md

Latest commit

 

History

History
85 lines (73 loc) · 3.35 KB

project-structure.md

File metadata and controls

85 lines (73 loc) · 3.35 KB
Raw

Project Structure Guide

This document explains the folder layout and the main files in this repository. Use it as the first reference when you need to understand where to add or modify files.

Top-Level Overview

  • .github/
    • Repository-level AI and review prompts.
  • archetypes/
    • Hugo content archetypes (default front matter templates).
  • assets/
    • Source assets processed by Hugo Pipes.
    • css/: SCSS sources for theme styles.
    • ts/: TypeScript sources bundled by Hugo.
  • exampleSite/
    • Example Hugo site for local testing and previews.
    • content/: sample pages and posts, organized by language directories (for example content/ja/, content/en/, content/zh-cn/).
    • layouts/partials/: example-site-specific partial overrides.
    • public/: generated output (build artifact).
  • images/
    • Image assets used by the theme/site.
  • layouts/
    • Core Hugo templates for the theme.
    • _default/: base templates for list/single/summary pages.
    • partials/: reusable template fragments.
    • shortcodes/: custom shortcode templates.
  • resources/
    • Hugo-generated cache/artifacts (_gen/ is generated content).
  • static/
    • Files served as-is (for example robots.txt, static images).
  • docs/
    • Project documentation, including this file.

Main Configuration and Metadata Files

  • config/_default/
    • Theme-level Hugo configuration defaults split by root key.
    • Typical files in this repository include hugo.yaml, params.yaml, menus.yaml, outputs.yaml, outputFormats.yaml, permalinks.yaml, and module.yaml.
  • theme.toml
    • Hugo theme metadata.
  • package.json
    • Node dependencies and scripts used for development tasks.
  • package-lock.json
    • Exact resolved dependency versions.
  • exampleSite/packages/hugoautogen/package.json
    • Hugo-generated npm dependency snapshot created by hugo mod npm pack.
  • go.mod
    • Go module declaration (used by Hugo module workflows).
  • README.md
    • Main usage and setup instructions.

For consumer sites, a single hugo.yaml is still valid. This repository uses config/_default/ to keep large theme settings easier to maintain.

Template and Asset Entry Points

  • layouts/_default/baseof.html
    • Base layout wrapper for pages.
  • layouts/partials/head.html
    • Shared head elements, CSS/JS includes, and CDN resources.
  • layouts/partials/header.html / layouts/partials/footer.html
    • Shared page chrome.
  • assets/css/styles.scss
    • Main SCSS entry point.
  • assets/ts/color-module.ts
    • Theme color mode behavior.
  • assets/ts/algolia.ts
    • Algolia search UI behavior.

Working Rules for File Placement

  • Prefer editing existing partials in layouts/partials/ instead of duplicating markup.
  • Place global style changes in assets/css/ and keep widget-specific rules in assets/css/widgets/.
  • Place client-side logic in assets/ts/ and keep feature scope narrow.
  • Use exampleSite/ for testing behavior and content examples.
  • Treat exampleSite/public/ and resources/_gen/ as generated outputs unless a task explicitly requires them.

Quick Navigation Tips

  • New page rendering behavior: start with layouts/_default/.
  • Shared UI elements: start with layouts/partials/.
  • Visual style updates: start with assets/css/.
  • Script behavior updates: start with assets/ts/.
  • Review expectations for PRs: see .github/prompts/review.prompt.md.