Step-by-step instructions to build and maintain a Hugo + PaperMod + AsciiDoc static site on GitHub Pages.
Prerequisites Homebrew (macOS) or equivalent package manager
Git
Hugo Extended (installed via Homebrew)
brew install hugo hugo version Verify the output includes extended:
hugo v0.164.0+extended ... Asciidoctor Hugo requires asciidoctor to process .adoc files:
brew install asciidoctor gem install asciidoctor Verify:
asciidoctor --version Project Setup Create a New Site hugo new site my-site cd my-site Add the PaperMod Theme git init git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod themes/PaperMod Configure hugo.toml baseURL = "https://example.com/" locale = "en" title = "My Site" theme = "PaperMod" paginate = 10 enableRobotsTXT = true enableEmoji = true [params] description = "Site description" author = "Your Name" defaultTheme = "auto" ShowReadingTime = true ShowToc = true ShowCodeCopyButtons = true [taxonomies] tag = "tags" category = "categories" [menu] main = [ { identifier = "posts", name = "Posts", url = "/posts/", weight = 10 }, { identifier = "about", name = "About", url = "/about/", weight = 20 }, ] [security.exec] allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$', '^asciidoctor$'] [markup.asciidocExt] workingFolderCurrent = true noHeaderOrFooter = true safeMode = "unsafe" attributes = { icons = "font", idseparator = "_", source-highlighter = "rouge", "rouge-style" = "monokai", experimental = true, sectanchors = true } Create Content Directory Structure mkdir -p content/posts mkdir -p static/images mkdir -p content/arch Create an About Page cat > content/about.md << 'EOF' --- title: "About" date: 2026-01-01 --- Your about page content here. EOF Create a First Post --- title: "My First Post" date: 2026-07-07 showToc: true --- = My First Post Content in AsciiDoc format. == Section Heading * Bullet point * Another point [source,sh] echo "Code block"
...