Skip to content

Authoring-Guide.md

Latest commit

 

History

History
208 lines (142 loc) · 4.53 KB

Authoring-Guide.md

File metadata and controls

208 lines (142 loc) · 4.53 KB
Raw

Authoring Guide

Content is written in the private vault as Markdown. The sync script copies only published content into this repo, then src/lib/content.ts renders it with standard Markdown plus a small set of custom directives.

Use this guide when writing or reviewing vault content.

General Rules

  • Keep frontmatter factual and public-safe.
  • Set published: true only when the page or writeup is ready to ship.
  • Put writeup images in the writeup's local images/ folder.
  • Reference local images as ./images/file.png.
  • Start writeup body sections at ##; the article title is already rendered as the page h1.
  • Prefer normal Markdown unless a directive adds real structure.
  • Do not rely on raw HTML unless there is a specific reason.

Image Syntax

Standard image:

![Screenshot of the final dashboard](./images/dashboard.png)

The alt text is used as the visible caption when the image is promoted to a figure.

Width override:

![Packet capture showing ARP replies|720](./images/arp-replies.png)

No visible caption:

![Joe Severino portrait|nocap](./images/portrait.jpg)

Opt out of the zoom view:

![Decorative divider|nozoom](./images/divider.svg)

Every image in the article body opens an enlarged zoom view on click or tap by default. Add |nozoom to keep a specific image static; it still renders normally. The |nozoom modifier also works inside ::figure blocks.

The sync pipeline generates responsive variants. Picture.astro renders AVIF, WebP, and fallback sources with stable dimensions.

Terminal Blocks

Use terminal blocks for command/output sequences.

::terminal
$ npm run publish:check
check      0 errors, 0 warnings
build      76 pages built
::

Lines beginning with $ are rendered as commands. Other lines are rendered as output.

Buttons

Single button:

::button [View Resume](/resume/) ::

Sticky button:

::button sticky [Download PDF](/assets/resume.pdf) ::

Button row:

::buttons
- [View Portfolio](/portfolio/)
- [Contact Me](/contact/)
::

Standard CTA:

::cta ::

The standard CTA is generated by the renderer and points to the portfolio and contact pages.

Centered Content

Use sparingly for short page-opening text.

::center
Cybersecurity and networking projects.
::

Split Layout

Use a split layout for two-column page sections.

::split
Left column content.
:::
Right column content.
::

The ::: line separates the two columns.

Hero

Wraps the home-page hero in a centered <header>. Use once, at the top of the home page.

::hero
<p class="hero-eyebrow">Cybersecurity • Networking</p>

# Hi, I'm Joe Severino

Role • Credentials

<p class="hero-summary">One-line summary of the work.</p>

<p class="hero-location">City, State</p>

::buttons
- [View My Resume](/resume/)
- [Get in Touch](/contact/)
::
::

The hero-eyebrow, hero-summary, and hero-location classes style the kicker, the lead summary, and the location chip.

Dynamic Page Blocks

These are mainly for top-level pages.

Featured projects:

::featured-projects ::

Technology cloud:

::technology-cloud ::

Both are generated from structured content. Featured projects come from writeup frontmatter. Technology groups come from src/content/technology-groups.md.

Figure Blocks

Use figure blocks when a caption needs Markdown or multiple lines.

::figure
![Nftables host filter](./images/nftables.png)
The host firewall accepts SSH only from Tailscale and the home LAN fallback.
::

Table Blocks

Use table blocks when a table needs a caption.

::table
| Control | Purpose |
| --- | --- |
| Turnstile | Bot challenge |
| D1 | Contact messages and CSP reports |

Contact form controls.
::

Tables are wrapped for horizontal scrolling on small screens.

Review Checklist

Before publishing:

  • The page or writeup has published: true.
  • The title and description are public-safe.
  • Images use local relative paths.
  • Captions are descriptive.
  • No private hostnames, keys, internal notes, or vault metadata appear in body content.
  • npm run publish:check passes after sync (see Pre-flight Validation).

Related Docs