Documentation for New Website

Initial file/directory structure

$ tree ../experimental_website/ -L 2
../experimental_website/
├── antora-playbook.yml
├── antora-ui-default
│   ├── build
│   ├── docs
│   ├── gulp.d
│   ├── gulpfile.js
│   ├── index.js
│   ├── LICENSE
│   ├── node_modules
│   ├── package.json
│   ├── package-lock.json
│   ├── preview-src
│   ├── public
│   ├── README.adoc
│   ├── rebuild.sh
│   └── src
├── build
│   └── site
├── make.sh
├── mycomponents
│   ├── advanced
│   ├── beginner
│   ├── frontmatter
│   └── intermediate
├── post-process-html.js
├── supplemental-ui
│   └── css
└── upload.sh

antora-playbook.yml

site:
  title: Practical Computing
  url: /
  start_page: frontmatter::index.adoc

content:
  sources:
    - url: ./mycomponents/beginner
    - url: ./mycomponents/intermediate
    - url: ./mycomponents/advanced
    - url: ./mycomponents/frontmatter

ui:
  bundle:
    url: /home/vern/Documents/experimental_website/antora-ui-default/build/ui-bundle.zip
  supplemental_files: ./supplemental-ui

antora:
  extensions:
    - '@antora/collector-extension'
    - ./post-process-html.js
    - require: '@antora/lunr-extension'

asciidoc:
  attributes:
    source-highlighter: ~
    html-attributes: true

antora-ui-default/src

$ tree antora-ui-default/src
antora-ui-default/src
├── css
│   ├── base.css
│   ├── body.css
│   ├── breadcrumbs.css
│   ├── doc.css
│   ├── footer.css
│   ├── header.css
│   ├── highlight.css
│   ├── main.css
│   ├── nav.css
│   ├── page-versions.css
│   ├── pagination.css
│   ├── print.css
│   ├── prism.css
│   ├── site.css
│   ├── toc.css
│   ├── toolbar.css
│   ├── typeface-roboto.css
│   ├── typeface-roboto-mono.css
│   ├── vars.css
│   └── vendor
│       └── prism.css
├── helpers
│   ├── and.js
│   ├── detag.js
│   ├── eq.js
│   ├── increment.js
│   ├── ne.js
│   ├── not.js
│   ├── or.js
│   ├── relativize.js
│   └── year.js
├── img
│   ├── back.svg
│   ├── caret.svg
│   ├── chevron.svg
│   ├── favicon.ico
│   ├── home-o.svg
│   ├── home.svg
│   ├── menu.svg
│   └── octicons-16.svg
├── js
│   ├── 01-nav.js
│   ├── 02-on-this-page.js
│   ├── 03-fragment-jumper.js
│   ├── 04-page-versions.js
│   ├── 05-mobile-navbar.js
│   ├── 06-copy-to-clipboard.js
│   ├── 07-breadcrumbs.js
│   └── vendor
│       └── prism.js
├── layouts
│   ├── 404.hbs
│   └── default.hbs
└── partials
    ├── article-404.hbs
    ├── article.hbs
    ├── body.hbs
    ├── breadcrumbs.hbs
    ├── edit-this-page.hbs
    ├── footer-content.hbs
    ├── footer.hbs
    ├── footer-scripts.hbs
    ├── header-content.hbs
    ├── header.hbs
    ├── header-scripts.hbs
    ├── head.hbs
    ├── head-icons.hbs
    ├── head-info.hbs
    ├── head-meta.hbs
    ├── head-prelude.hbs
    ├── head-scripts.hbs
    ├── head-styles.hbs
    ├── head-title.hbs
    ├── main.hbs
    ├── nav-explore.hbs
    ├── nav.hbs
    ├── nav-menu.hbs
    ├── nav-toggle.hbs
    ├── nav-tree.hbs
    ├── page-versions.hbs
    ├── pagination.hbs
    ├── toc.hbs
    └── toolbar.hbs

Files in partials that are modified:

footer-scripts.hbs, head.hbs, header-content.hbs

header-content.hbs
<header class="header">
  <nav class="navbar">
    <div class="navbar-brand">
      <a class="navbar-item" href="{{{or site.url siteRootPath}}}">{{site.title}}</a>
      {{#if env.SITE_SEARCH_PROVIDER}}
      <div class="navbar-item search hide-for-print">
        <div id="search-field" class="field">
          <input id="search-input" type="text" placeholder="Search the docs"{{#if page.home}} autofocus{{/if}}>
        </div>
      </div>
      {{/if}}
      <button class="navbar-burger" aria-controls="topbar-nav" aria-expanded="false" aria-label="Toggle main menu">
        <span></span>
        <span></span>
        <span></span>
      </button>
    </div>
    <div id="topbar-nav" class="navbar-menu">
      <div class="navbar-end">
        <div class="navbar-item has-dropdown is-hoverable">
          <div class="navbar-dropdown">
          </div>
        </div>
        <div class="navbar-item has-dropdown is-hoverable">
          <div class="navbar-dropdown">
          </div>
        </div>
        <div class="navbar-item">
          <span class="control">
          </span>
        </div>
      </div>
    </div>
  </nav>
</header>

Removed all <a> tags to take out all the links in the top section where search bar is located

head.hbs
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>{{{detag (or page.title 'Untitled')}}}{{#if site.title}} | {{{site.title}}}{{/if}}</title>
<link rel="icon" href="{{{uiRootPath}}}/img/favicon.ico" type="image/x-icon">
{{#if page.canonicalUrl}}
<link rel="canonical" href="{{page.canonicalUrl}}">
{{/if}}
{{#if page.description}}
<meta name="description" content="{{page.description}}">
{{/if}}
{{#if page.keywords}}
<meta name="keywords" content="{{page.keywords}}">
{{/if}}
<meta name="generator" content="Antora {{antoraVersion}}">
<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
{{!-- Add Prism.css below site.css so Prism can override default code styles --}}
<link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/prism.css">
<link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/adoc_other_fixes.css">
{{> head-scripts}}
{{#if page.attributes.prev}}
<link rel="prev" href="{{{relativize page.url page.attributes.prev}}}">
{{/if}}
{{#if page.attributes.next}}
<link rel="next" href="{{{relativize page.url page.attributes.next}}}">
{{/if}}

Line 18 added to make use of adoc_other_fixes.css, shown below.

footer-scripts.hbs
<script id="site-script" src="{{{uiRootPath}}}/js/site.js" data-ui-root-path="{{{uiRootPath}}}"></script>

{{!-- 1. Load Prism.js Core --}}
<script src="{{{uiRootPath}}}/js/vendor/prism.js"></script>

<script>
  (function() {
    function applyPrism() {
      document.querySelectorAll('.listingblock').forEach(function(block) {
        var pre = block.querySelector('pre');
        if (!pre) return;

        block.classList.forEach(function(cls) {
          // Trigger numbers if role is [.line-numbers] or [.linenums]
          if (cls === 'line-numbers' || cls === 'linenums') {
            pre.classList.add('line-numbers');
          }

          // Handle Start and FORCE numbers
          if (cls.startsWith('line-start-')) {
            pre.setAttribute('data-start', cls.replace('line-start-', ''));
            pre.classList.add('line-numbers');
          }

          // Handle Highlights and FORCE numbers
          if (cls.startsWith('highlight-lines-')) {
            var val = cls.replace('highlight-lines-', '').replace(/_/g, ',');
            pre.setAttribute('data-line', val);
            pre.classList.add('line-numbers'); // <--- ADD THIS LINE
          }
        });
      });

      if (window.Prism) {
        Prism.highlightAll();
      }
    }
    window.addEventListener('load', applyPrism);
  })();
</script>





{{!-- 3. Core Search Integration (Do not remove) --}}
{{#if env.SITE_SEARCH_PROVIDER}}
{{> search-scripts}}
{{/if}}

The applyPrism() function will take the html attributes for the source code blocks and put in the correct class attributes needed for Prism.js to do the source code formatting for line-numbers, data-line, data-start, data-line-offest.

Created the file ~/Documents/experimental_website/antora-ui-default/src/css/vendor/adoc_other_fixes.css. This took all the fixes that were at the end of the prism.css and placed them into this file. That way, if prism.css has to be downloaded again this will not have to be added to prism.css.

adoc_other_fixes.css
/* --- ASCIIDOCTOR CLASSIC LOOK OVERRIDES --- */

/* 1. Headings: Sizes and Underlines */
.doc h1.page { font-size: 2.125rem !important; border-bottom: 1px solid #dddddd; padding-bottom: 0.3em; }
.doc h2 { font-size: 1.6875rem !important; border-bottom: 1px solid #dddddd; padding-bottom: 0.3em; margin-top: 1.5rem; }
.doc h3 { font-size: 1.375rem !important; margin-top: 1.25rem; }
.doc h1, .doc h2, .doc h3 { color: #333333; font-weight: 400; }

/* 2. TOC: Blue and Underlined */
.toc .toc-menu a {
    color: #0056b3 !important;
    text-decoration: underline !important;
    text-underline-offset: 2px;
    font-size: 0.9rem !important;
}
.toc .toc-menu a:hover { color: #003d80 !important; }

/* 3. Code Block Neutralization (from previous steps) */
.doc pre.highlight > code {
    overflow-x: visible !important;
    padding: 0 !important;
    background: none !important;
}

/* --- CLASSIC ASCIIDOC TYPOGRAPHY & COLORS --- */

/* 1. Use the classic Serif font stack for headings */
.doc h1, .doc h2, .doc h3, .doc h4, .doc h5, .doc h6 {
    font-family: "Noto Serif", "Georgia", "Times New Roman", serif !important;
    font-weight: 400 !important;
    text-rendering: optimizeLegibility;
}

/* 2. Classic Asciidoc Heading Colors */
.doc h1.page {
    color: #ba3925 !important; /* The iconic dark red/brown H1 */
}

.doc h2, .doc h3, .doc h4 {
    color: #7a2518 !important; /* Darker mahogany for sub-headers */
    /* Alternatively, use #333333 if you prefer the neutral dark grey */
}

/* 3. Re-adjust the TOC Font to match */
.toc .toc-menu {
    font-family: "Noto Serif", "Georgia", serif;
}

/* --- GLOBAL TYPOGRAPHY OVERRIDE --- */

/* Change the main body text to Noto Serif */
.doc {
    font-family: "Noto Serif", "Georgia", "Times New Roman", serif !important;
    font-size: 1.0625rem; /* Classic Asciidoctor base font size */
    line-height: 1.6;     /* Comfortable reading height for serif fonts */
    color: #333333;       /* Standard Asciidoctor text color */
}

/* Ensure paragraph spacing matches the classic feel */
.doc p {
    margin-bottom: 1.25rem;
}

/* Keep the UI navigation/menus as Sans-Serif (Standard Antora behavior) */
/* If you want the navigation to stay Roboto, don't change anything else. */

/* --- PNG IMAGE HOVER EFFECT (EXCLUDING GIFS) --- */

/* 1. Target only <img> tags where the 'src' attribute ends in .png */
.doc img[src$=".png"] {
    transition: transform 0.5s ease-in-out;
    cursor: zoom-in;
    transform-origin: center center; /* Ensures it scales from the middle */
}

/* 2. Apply scale only to the PNGs on hover */
.doc img[src$=".png"]:hover {
    transform: scale(1.25);
    position: relative;
    z-index: 10;
    box-shadow: 0 8px 16px rgba(0,0,0,0.3); /* Gives the 'popped' effect */
    border-radius: 2px; /* Optional: keeps corners clean while scaling */
}

/* 3. Explicitly ensure .gif files stay static (Optional/Safety) */
.doc img[src$=".gif"]:hover {
    transform: none !important;
    box-shadow: none !important;
}
/* Push the main page content down so the H1 isn't buried */
.doc {
    padding-top: 2rem !important;
}

/* Specifically ensure the H1 title has enough breathing room */
.doc h1.page {
    margin-top: 1.5rem !important;
    padding-top: 0.5rem;
}

supplemental-ui files

supplemental-ui/css/site.css

The site.css from the practical.compute.cc site was used here so that line-numbers show up.

Prism.js downloaded options

Minified version, core, default theme

Languages selected:

Default choices
markup, css, c-like, javascript
Additional languages
C, C#, C++
Dart, Diff, Docker
Handlebars
Java, JSdoc
JSON + Web App Manifest
Markup templateing
PHP, Python
Ruby, Rust
SQL
TypeScript
WebAssembly
YAML
Plugins selected
Line Highlight
Line Numbers
Remove initial line feed
Normalize Whitespace

New way of defining source code blocks

linenums,data-line="11,12"
[.highlight-lines-11-12]
[source,javascript]


linenums,data-line="9-10,16-18"
[.highlight-lines-9-10_16-18]
[source,javascript]

linenums,data-line="105-110",data-start="100",data-line-offset="100"
[.line-start-100.line-offset-100.highlight-lines-105-110]
[source,javascript]

linenums,data-start="20"  (no lines are highlighted)
[.line-start-20]
[source,javascript]