fast-adoc-blog

Framework Feature Tour

Sep 1, 2025 · 2 min read

Josh Kurz
Josh Kurz

An in-depth walkthrough demonstrating every core feature of fast-adoc-blog with hands-on examples.

Welcome to the feature tour. This post demonstrates the goodies available when writing in fast-adoc-blog.

AsciiDoc Basics

Inline formatting like bold, italic, and mono works out of the box. Attributes at the top control metadata and layout.

Lists & Tables

  1. Ordered list item

    1. Nested item

      • Unordered list

      • Another item

Column A Column B

A1

B1

A2

B2

Code Blocks & Callouts

function hello(name) {
  return `Hello, ${name}`; // (1)
}

  1. Callouts annotate lines of code.

Admonitions

Note

Use built-in admonitions for tips and warnings.
Tip

Mix multiple admonition types to draw attention to key information.

Images

Alt text

Custom Scripts & APIs

This demo fetches a serverless function using a custom script.

// api/ping.js
export default function handler(req, res) {
  res.status(200).json({ ok: true });
}











Theme Options






CSS variables are mapped to giscus theme names. Click a theme to preview it locally—the giscus widget follows suit. Set theme in config.json to persist a choice.












CSS data-theme
Matches giscus theme









light








light_high_contrast








dark








dark_dimmed








noborder_dark








Follows OS preference






















Feature Summary












Feature
What it shows







Responsive images


image:: macros stretch to fit the container






Live theme preview


Buttons swap CSS and giscus themes






Serverless ping demo


JS fetches /api/ping and prints JSON






Comments


Each post maps to a giscus discussion













Simple Config






Configuration lives in a single JSON file:








{
  "theme": "transparent_dark",
  "commentsProvider": "giscus",
  "giscus": {
    "mapping": "pathname",
    "theme": "noborder_dark"
  }
}












Deploy & License






Push to GitHub and Vercel builds the site instantly. The project ships under the MIT license—fork freely.










Comments






The giscus widget below maps each post to a matching GitHub discussion.






To enable comments on your own blog, run npm run dev and open /setup. Paste the giscus script from https://giscus.app into the form and it will write a config.json like:








{
  "commentsProvider": "giscus",
  "giscus": {
    "repo": "youruser/yourrepo",
    "repoId": "YOUR_REPO_ID",
    "category": "General",
    "categoryId": "YOUR_CATEGORY_ID",
    "mapping": "pathname",
    "theme": "noborder_dark"
  }
}








Commit that file and rebuild—each post will then show its own discussion thread.