nx1.info | How to Make a Dope Tutorial Page

A specification for building lightweight, zero-dependency, terminal-aesthetic notes.

1. The Zero-Runtime Philosophy [^]

Most syntax-highlighting solutions (e.g., highlight.js, prism.js) operate at runtime via JavaScript. While acceptable for standard blogs, this approach has several drawbacks: 1. Layout shifts & latency: The client renders plain unstyled text, fetches remote JS/CSS assets from CDNs, parses the DOM, and re-renders tokens, creating visual stutter. 2. Loss of terminal fidelity: Generic bash parsers fail on real terminal output—they cannot accurately distinguish between command inputs, git diff additions/deletions, and CLI status output. 3. Fragility & offline failure: If a CDN is blocked or offline, styling degrades. By contrast, pure semantic HTML + embedded CSS renders instantly on the first frame, works 100% offline, introduces zero JavaScript dependencies, and gives absolute control over every token's color.

2. DOM Layout & Monospace Preservation [^]

Every tutorial on nx1.info wraps its content inside a preformatted monospace container:

<body>
<div style="font-family: monospace; white-space: pre;">
<!-- Page content, headers, TOC, and preformatted blocks -->
</div>
</body>

Using white-space: pre; ensures that newlines and whitespace behave exactly like a terminal output stream (e.g. `cat` or `less`). Code blocks are then wrapped inside:

<pre class="term"><code>...</code></pre>

3. Complete Embedded CSS Boilerplate [^]

Include this `<style>` block in the `<head>` section of the page:

<style>
    /* Terminal code block container */
    pre.term {
        background-color: #0d1117;
        border: 1px solid #30363d;
        border-left: 3px solid #58a6ff;
        border-radius: 4px;
        padding: 8px 12px;
        margin: 6px 0;
        overflow-x: auto;
        font-family: inherit;
    }
    pre.term code {
        font-family: inherit;
        color: #c9d1d9;
    }

    /* Syntax token colors */
    .prompt  { color: #58a6ff; }                             /* >, $, # */
    .cmd     { color: #79c0ff; font-weight: bold; }       /* git, tmux, ip, vim */
    .sub     { color: #ffa657; }                             /* checkout, commit, addr */
    .flag    { color: #d2a8ff; }                             /* -b, --oneline, -f */
    .arg     { color: #e6edf3; }                             /* branch names, file targets */
    .str     { color: #a5d6ff; }                             /* "string values" */
    .key     { color: #f2cc60; font-weight: bold; }       /* keybindings, config keys */
    .action  { color: #c9d1d9; }                             /* description / action text */
    .comment { color: #8b949e; }                             /* # explanations */
    .hash    { color: #f2cc60; font-weight: bold; }       /* commit hashes */
    .branch  { color: #7ee787; font-weight: bold; }       /* local branches */
    .remote  { color: #ff7b72; }                             /* remotes (origin/master) */
    .add     { color: #7ee787; }                             /* additions, insertions */
    .del     { color: #ff7b72; }                             /* deletions, modified */

    /* Table of Contents */
    .toc-box {
        background-color: #0d1117;
        border: 1px solid #30363d;
        border-radius: 4px;
        padding: 12px 16px;
        margin: 14px 0 20px 0;
        display: inline-block;
    }
    .toc-header { color: #58a6ff; font-weight: bold; }
    .toc-cat    { color: #7ee787; font-weight: bold; }
    .top-link   { font-size: 0.75em; color: #8b949e; text-decoration: none; margin-left: 8px; }
    .top-link:hover { color: #58a6ff; }
    a:hover     { text-decoration: underline; }
</style>

4. Terminal Color Token Palette [^]

Tokens map to logical elements of shell and editor sessions:

>           <-- .prompt  (Cyan #58a6ff)
git         <-- .cmd     (Bold light blue #79c0ff)
checkout    <-- .sub     (Amber #ffa657)
-b          <-- .flag    (Purple #d2a8ff)
newbranch   <-- .arg     (Crisp white #e6edf3)
"message"   <-- .str     (Soft blue #a5d6ff)
Ctrl+b      <-- .key     (Gold #f2cc60)
00fa98c     <-- .hash    (Gold #f2cc60)
master      <-- .branch  (Terminal green #7ee787)
origin/main <-- .remote  (Coral red #ff7b72)
+ added     <-- .add     (Green #7ee787)
- removed   <-- .del     (Red #ff7b72)
# comment   <-- .comment (Muted grey #8b949e)

5. Terminal Table of Contents Frame [^]

Place the TOC at the top of the body immediately below the title:

<div id="toc" class="toc-box">
<span class="toc-header">Table of Contents:</span>
------------------
<span class="toc-cat">Category One:</span>
    <a href="#section-1">first topic title</a>
    <a href="#section-2">second topic title</a>

<span class="toc-cat">Category Two:</span>
    <a href="#section-3">third topic title</a>
</div>

6. Anchor Links & Header Back-Links ([^]) [^]

Every section heading must specify the corresponding `id` and include a back-to-top jump link:

<h2 id="section-1">First Topic Title <a href="#toc" class="top-link">[^]</a></h2>

Clicking `[^]` instantly scrolls the viewport back to `#toc`.

7. Step-by-Step Document Construction [^]

When converting raw notes into a tutorial: 1. Add the header and CSS boilerplate into `<head>`. 2. Identify the logical sections and write headings (`<h2>` with `id="..."`). 3. Add the `<div id="toc">` with categorized anchor links. 4. Wrap command sequences in `<pre class="term"><code>...</code></pre>`. 5. Apply token spans to prompts, executables, subcommands, flags, and comments.

8. Visual Selection Wrapping in Neovim [^]

In Neovim, you can map a keybinding to wrap visual line selections into terminal code blocks. Add to your `init.lua`:

-- Wrap visual selection in terminal pre block
vim.keymap.set("v", "<leader>tc", [[c<pre class="term"><code><CR><C-r>"<CR></code></pre><Esc>]], { remap = false })

Or in legacy `init.vim`:

vnoremap <leader>tc c<pre class="term"><code><CR><C-r>"<CR></code></pre><Esc>

9. Regex Substitutions for Fast Tagging [^]

Execute these commands across a visual selection (`:'<,'>`) or buffer in Neovim:

" Tag prompt symbols
:s/^> /<span class="prompt">><\/span> /g

" Tag git executable
:s/\<git\>/<span class="cmd">git<\/span>/g

" Tag flags (-b, --oneline, etc.)
:s/\(--\?[a-zA-Z0-9_-]\+\)/<span class="flag">\1<\/span>/g

" Tag inline comments
:s/\(#.*\)$/<span class="comment">\1<\/span>/g

10. Batch Automation Python Script [^]

For converting plain `.txt` or untagged `.html` files, run this Python script:

import re

def tag_line(line):
    # 1. Prompt
    line = re.sub(r'^(>\s*|\$\s*)', r'<span class="prompt">\1</span>', line)
    # 2. Primary command
    line = re.sub(r'\b(git|tmux|ip|nmcli|sudo|vim|ssh-add)\b', r'<span class="cmd">\1</span>', line)
    # 3. Subcommand
    line = re.sub(r'\b(checkout|branch|commit|push|pull|rebase|merge|stash|diff|log|add|show|status|addr|route|con)\b', r'<span class="sub">\1</span>', line)
    # 4. Flags
    line = re.sub(r'(\-{1,2}[a-zA-Z0-9_\-]+)', r'<span class="flag">\1</span>', line)
    # 5. Comments
    line = re.sub(r'(#.*)$', r'<span class="comment">\1</span>', line)
    return line

---