Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/theme-bulletin/llms.txt

Use this file to discover all available pages before exploring further.

Forking a ThemeBulletin theme and swapping your name and colors is just the beginning. Because every theme is a self-contained static site — a single HTML file with linked CSS and optional JavaScript — the architecture is transparent and fully under your control. This guide covers the advanced workflows: running the theme locally with a live-reload dev server, adding new content sections, publishing to a custom domain, and adapting a theme’s structure to a different technology stack.

​
Understanding the Static Site Structure

Each ThemeBulletin theme is built around a deliberately simple file structure: 
theme-repo/
├── index.html          # The entire portfolio — one HTML file
├── assets/
│   ├── css/
│   │   └── style.css   # All theme styles, including :root variables
│   ├── js/
│   │   └── main.js     # Optional JavaScript (interactions, animations)
│   └── images/         # Theme imagery and background assets
└── package.json        # Dev tooling only (servor dev server)
There are no compiled assets, no import graphs, and no framework. Everything the browser needs is linked directly from index.html. This means the site works by simply opening index.html in a browser — no server required for basic viewing.

​
Running the Theme Locally

ThemeBulletin themes include a package.json with a single start script that launches servor, a minimal zero-config static file server with live reload: 
{
  "scripts": {
    "start": "servor --reload"
  },
  "dependencies": {
    "servor": "^4.0.2"
  }
}
To run the theme locally: 
# Install the servor dependency
npm install

# Start the live-reload dev server
npm start
The server opens your default browser to http://localhost:8080 (or the next available port) and watches for file changes. When you save a file, the browser reloads automatically.
The servor dev server is the only Node.js dependency in each theme. It is a dev-only tool and has no effect on the deployed static files. You can delete node_modules/ and package-lock.json before committing without affecting the GitHub Pages deployment.

​
Adding New Sections to the HTML

Because each theme is a single index.html file, adding a new section (for example, a certifications section or a blog link) means adding new HTML inside <main>. Follow the existing pattern in the file — each theme uses consistent class names and structural conventions. For example, if a theme uses <section class="panel"> elements to display content blocks, add your new section in the same format: 
<!-- Existing section pattern -->
<section class="panel">
  <h2>Projects</h2>
  <ul>
    <li><a href="https://github.com/you/project">Project Name</a> — short description</li>
  </ul>
</section>

<!-- New section following the same pattern -->
<section class="panel">
  <h2>Certifications</h2>
  <ul>
    <li>AWS Certified Solutions Architect – Associate (2024)</li>
    <li>Google Professional Cloud Developer (2023)</li>
  </ul>
</section>
Add corresponding CSS for your new section in assets/css/style.css. Use the existing CSS custom properties (--bg, --a, --b, --fg) so your new section inherits the theme’s color palette automatically.

​
Updating the <head> — Title, Meta Description, and Open Graph

Every time you adapt a theme to your own portfolio, update the <head> section completely. The key fields are: 
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- Page identity — update these -->
  <title>Your Name — Portfolio</title>
  <meta name="description" content="Your Name is a software engineer specializing in distributed systems, based in Seattle, WA.">

  <!-- Open Graph — controls how the page appears when shared on social media -->
  <meta property="og:title" content="Your Name — Portfolio">
  <meta property="og:description" content="Software engineer. Distributed systems. Seattle.">
  <meta property="og:url" content="https://yourusername.github.io/">
  <meta property="og:type" content="website">
</head>
If you skip updating the <title> and <meta name="description">, your portfolio will be indexed by search engines under the original theme name (e.g. “Developer Dossier Theme | ThemeBulletin”). Always update these before publishing.

​
Hosting on a Custom Domain via GitHub Pages CNAME

To serve your forked theme at a custom domain (for example, yourname.dev): Step 1 — Add a CNAME file to your repository root. Create a file named CNAME (no file extension) containing only your domain: 
yourname.dev
Commit and push this file. GitHub Pages will read it automatically and configure routing for your domain. Step 2 — Configure DNS at your registrar. For a www subdomain, create a CNAME DNS record pointing www.yourname.dev to yourusername.github.io. For an apex domain (yourname.dev), create four A records pointing to GitHub Pages’ IP addresses (see the GitHub Pages documentation for current IPs). Step 3 — Enable HTTPS. Once DNS has propagated and GitHub Pages confirms your domain, enable Enforce HTTPS in your repository’s Settings > Pages panel.
You can also add the CNAME file through the GitHub Pages settings UI — GitHub will commit it to your repository automatically. Either approach works.

​
Adding Multiple Pages

Each ThemeBulletin theme ships as a single-page portfolio, but there is nothing stopping you from adding additional HTML files. To add a second page (for example, a blog index):
  1. Create a new file — e.g. blog.html — in your repository root.
  2. Copy the <head> block from index.html (to get the same fonts and CSS link).
  3. Copy the <header> and <footer> from index.html for consistent navigation.
  4. Build your new page content in <main>.
  5. Add a link to blog.html in the navigation of index.html.
Because GitHub Pages serves all files in the repository, blog.html will be accessible at https://yourusername.github.io/repo-name/blog.html automatically.

​
Adapting a Theme to a Different Tech Stack

ThemeBulletin themes are vanilla static sites, but their visual designs can be adapted to other stacks if you want features like server-side rendering, a CMS, or a component framework. Some considerations:
  • Next.js or Astro — Copy the CSS custom properties and font imports into your project’s global stylesheet. Recreate the HTML structure as components. The single-page layouts translate directly to JSX or Astro component syntax.
  • Hugo or Jekyll — Use the theme’s HTML as a layout template. Replace static content with template variables (e.g. {{ .Title }}). Move the CSS into your static assets directory.
  • Any framework — The design is entirely in the CSS. The critical files to carry forward are the :root custom properties, the font <link> tags, and the structural class names used by the layout.
Adapting a theme to a different stack is entirely your choice — the ThemeBulletin licenses are standard open-source GitHub repositories and each theme’s repository will contain its license information.

Build docs developers (and LLMs) love

Get started for freeTalk to us