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 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
<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.
<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.
/* --- 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;
}
Prism.js downloaded options
Minified version, core, default theme
Languages selected:
markup, css, c-like, javascript
C, C#, C++
Dart, Diff, Docker
Handlebars
Java, JSdoc
JSON + Web App Manifest
Markup templateing
PHP, Python
Ruby, Rust
SQL
TypeScript
WebAssembly
YAML
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]