gethtmlpress 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
# Htmlpress
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
without a framework, a build config or
|
|
3
|
+
The static site generator for humans and agents. Htmlpress turns a folder of Markdown and
|
|
4
|
+
HTML pages into a site. Each page keeps its own markup, and htmlpress adds one layout, one
|
|
5
|
+
theme, a navigation and a live-reloading dev server. You or your agent write plain Markdown
|
|
6
|
+
or semantic HTML, and the result looks consistent without a framework, a build config or
|
|
7
|
+
Tailwind.
|
|
7
8
|
|
|
8
9
|
## Installation
|
|
9
10
|
|
|
@@ -25,7 +26,8 @@ htmlpress build docs --json # the result as JSON, for scripts and agents
|
|
|
25
26
|
htmlpress --llms # every command's input and output schema, for agents
|
|
26
27
|
```
|
|
27
28
|
|
|
28
|
-
A page is any `.html` file in the folder:
|
|
29
|
+
A page is any `.md` or `.html` file in the folder: Markdown with frontmatter, or HTML from a
|
|
30
|
+
fragment to a full document. Its `<title>`
|
|
29
31
|
(else its first `<h1>`) names it in the navigation, `<meta name="order" content="1">` sorts it,
|
|
30
32
|
and `index.html` comes first. Every other file is copied as-is.
|
|
31
33
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gethtmlpress",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Turn a folder of HTML pages into a site: one layout, one theme, live reload,
|
|
3
|
+
"version": "0.7.0",
|
|
4
|
+
"description": "Turn a folder of Markdown and HTML pages into a site: one layout, one theme, live reload, for humans and agents",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
7
7
|
"html",
|
|
@@ -30,11 +30,11 @@
|
|
|
30
30
|
"node": ">=20"
|
|
31
31
|
},
|
|
32
32
|
"optionalDependencies": {
|
|
33
|
-
"@htmlpress/linux-x64": "0.
|
|
34
|
-
"@htmlpress/linux-arm64": "0.
|
|
35
|
-
"@htmlpress/darwin-x64": "0.
|
|
36
|
-
"@htmlpress/darwin-arm64": "0.
|
|
37
|
-
"@htmlpress/win32-x64": "0.
|
|
38
|
-
"@htmlpress/win32-arm64": "0.
|
|
33
|
+
"@htmlpress/linux-x64": "0.7.0",
|
|
34
|
+
"@htmlpress/linux-arm64": "0.7.0",
|
|
35
|
+
"@htmlpress/darwin-x64": "0.7.0",
|
|
36
|
+
"@htmlpress/darwin-arm64": "0.7.0",
|
|
37
|
+
"@htmlpress/win32-x64": "0.7.0",
|
|
38
|
+
"@htmlpress/win32-arm64": "0.7.0"
|
|
39
39
|
}
|
|
40
40
|
}
|
|
@@ -37,16 +37,63 @@ The config keys are in `htmlpress-configuration`; a different look in `htmlpress
|
|
|
37
37
|
(`-1` pins a page last).
|
|
38
38
|
- Other `<head>` tags (`<link>`, `<style>`, `<script>`) are kept and added after the theme; a
|
|
39
39
|
fragment's are the ones before its first content, as a browser reads them.
|
|
40
|
-
- The navigation nests pages
|
|
41
|
-
|
|
40
|
+
- The navigation nests a folder's pages under its `index.html` at any depth (`guides/cli/…`
|
|
41
|
+
inside `guides/…`), whose title names and links the group and whose `order` places it; a
|
|
42
|
+
folder without an `index.html` makes no group, its pages sitting at the top.
|
|
42
43
|
- Each page is served at its own folder URL: `guides/build.html` at `/guides/build/`,
|
|
43
|
-
`guides/index.html` at `/guides
|
|
44
|
+
`guides/index.html` at `/guides/`, every name slugified as in Livemark
|
|
45
|
+
(`User Guide/Intro.html` at `/user-guide/intro/`). Link to the page file (`guides/build.html`, relative or
|
|
44
46
|
root-relative) or to its URL: a link naming a page's file becomes its URL. Images and other
|
|
45
47
|
files are copied as-is; a relative `href`, `src`, `srcset` or `poster` resolves from the
|
|
46
48
|
source file, even when the page moves.
|
|
47
49
|
- A root `404.html` is the not-found page, kept out of the navigation; without one a built-in
|
|
48
50
|
is used.
|
|
49
51
|
|
|
52
|
+
## Markdown pages
|
|
53
|
+
|
|
54
|
+
A `.md` file is a page too, served where its `.html` twin would be (`guide.md` at `/guide/`),
|
|
55
|
+
and goes through the same build: components, math, code blocks, includes, the TOC.
|
|
56
|
+
|
|
57
|
+
````md
|
|
58
|
+
---
|
|
59
|
+
title: Getting started
|
|
60
|
+
description: Install and run it in a minute.
|
|
61
|
+
order: 1
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
# Getting started
|
|
65
|
+
|
|
66
|
+
:::warning[Back up first]
|
|
67
|
+
The build wipes its output folder.
|
|
68
|
+
:::
|
|
69
|
+
|
|
70
|
+
```js title="build.js" lines="2"
|
|
71
|
+
await build("docs")
|
|
72
|
+
```
|
|
73
|
+
````
|
|
74
|
+
|
|
75
|
+
- The frontmatter keys are the page metas by the same names (`title`, `description`, `order`,
|
|
76
|
+
`layout`, `icon`, `label`, `sidebar`, `date`, `author`, `keywords`, …) plus `head`, raw HTML
|
|
77
|
+
for `<head>`; `author` and `keywords` take a list. Any other key fails the build.
|
|
78
|
+
- The syntax is Livemark's: `:::note|tip|info|warning|danger[title]` and `> [!NOTE]` alerts are
|
|
79
|
+
callouts; `:::card{title href icon}`, `:::column` and `:::tab{title sync}` in a row group into
|
|
80
|
+
cards, columns and tabs; `:::details[summary]`, `:::filetree`, `::button[label]{href variant
|
|
81
|
+
size}`, `::toc{maxLevel}`, `::video{type="youtube" url}`, `::audio{type="soundcloud" url}`,
|
|
82
|
+
`:badge[label]{variant}`, `:icon{name}`, `:abbr[text]{title}`. Headings take `{#id}`,
|
|
83
|
+
`[step]`, `[!toc]` and `[toc]`; `Term` then `: definition` is a definition list.
|
|
84
|
+
- Any other `:::name{attrs}` is the component `<htmlpress-name attrs>`; a block one that names
|
|
85
|
+
no component fails the build, while inline `note:important` stays text. Raw `<htmlpress-*>`
|
|
86
|
+
HTML works too, with Markdown inside after a blank line.
|
|
87
|
+
- A fence's meta is the code block attributes without `data-`: `title`, `collapse`, `lines`,
|
|
88
|
+
`line-numbers`, `add`, `remove`, `focus`, `error`, `warning`, `words`; adjacent fences with
|
|
89
|
+
`tab="…"` (and `sync`) are code tabs, ` ```npm ` is package-manager tabs, ` ```mermaid `
|
|
90
|
+
a diagram, and inline `` `code{:ts}` `` is highlighted.
|
|
91
|
+
- GitHub Markdown (tables, task lists, footnotes, autolinks), `$…$` math and `:emoji:` work.
|
|
92
|
+
Link to another page by its file, `[Setup](setup.md)`.
|
|
93
|
+
- Never pages: an `.md` beside its `.html` page (that page's own Markdown copy for agents),
|
|
94
|
+
an `.md` a page includes (a partial, with directives), a changelog section's `source`, and
|
|
95
|
+
the `skills` files.
|
|
96
|
+
|
|
50
97
|
## Page metas
|
|
51
98
|
|
|
52
99
|
| Meta | Effect |
|
|
@@ -79,9 +126,11 @@ The same holds for the default language without an `index.html`.
|
|
|
79
126
|
## Headings
|
|
80
127
|
|
|
81
128
|
- `<h2>` to `<h4>` outside components make the page's table of contents; any `<h2>` to `<h6>`
|
|
82
|
-
without an `id` gets a slug of its text
|
|
129
|
+
without an `id` gets a slug of its text, as GitHub makes them (`intro`, then `intro-1`), never
|
|
130
|
+
an `id` the page already uses, and an anchor link. Give a heading an `id` only when a link
|
|
131
|
+
needs it fixed.
|
|
83
132
|
- A heading takes `data-toc="false"` (shown, not in the TOC) or `data-toc="only"` (in the TOC,
|
|
84
|
-
not shown); `<htmlpress-toc level="2">` (2–4, default
|
|
133
|
+
not shown); `<htmlpress-toc max-level="2">` (2–4, default 4) in a page renders its TOC inline.
|
|
85
134
|
|
|
86
135
|
## The layout owns the frame
|
|
87
136
|
|
|
@@ -111,6 +160,7 @@ The theme styles the elements themselves: headings, `<p>`, lists, `<table>`, `<p
|
|
|
111
160
|
- No inline `style`, no classes for looks, no utility CSS: every page should look like the same
|
|
112
161
|
site. A site-wide change is a token (`htmlpress-customization`).
|
|
113
162
|
- An image with `data-theme="light"` or `"dark"` shows in that theme only.
|
|
163
|
+
- Every image opens full screen on click, unless a link wraps it; nothing to write.
|
|
114
164
|
- `<abbr title>` and footnote references (`<sup><a href="#n1">` to an `<li id="n1">`) show a
|
|
115
165
|
hover hint; headings get a link on their own.
|
|
116
166
|
- Bare URLs and emails in prose become links and GitHub shortcodes (`:rocket:`) become emoji at
|
|
@@ -119,7 +169,7 @@ The theme styles the elements themselves: headings, `<p>`, lists, `<table>`, `<p
|
|
|
119
169
|
is a dollar), or `<htmlpress-math display>…</htmlpress-math>`; rendered to MathML at build
|
|
120
170
|
time, and invalid LaTeX fails the build.
|
|
121
171
|
- `<htmlpress-include src="partial.html">` pastes in another file by path, relative to the page:
|
|
122
|
-
an `.html` body,
|
|
172
|
+
an `.html` body, compiled `.md` (directives and fence meta work), or any other file as a titled code block that takes
|
|
123
173
|
`data-lines` and the other code block attributes. Exclude the partials folder in the config.
|
|
124
174
|
|
|
125
175
|
## Code blocks
|
|
@@ -140,23 +190,21 @@ The theme styles the elements themselves: headings, `<p>`, lists, `<table>`, `<p
|
|
|
140
190
|
Only these; anything else is plain HTML. Put block content (`<p>`, `<h3>`, `<pre>`) inside a
|
|
141
191
|
component, not bare text.
|
|
142
192
|
|
|
143
|
-
| Element
|
|
144
|
-
|
|
|
145
|
-
| `<htmlpress-callout type="…"
|
|
146
|
-
| `<htmlpress-
|
|
147
|
-
| `<htmlpress-tabs sync="…">` + `<
|
|
148
|
-
| `<
|
|
149
|
-
| `<htmlpress-badge
|
|
150
|
-
| `<htmlpress-
|
|
151
|
-
| `<htmlpress-
|
|
152
|
-
| `<htmlpress-
|
|
153
|
-
| `<htmlpress-
|
|
154
|
-
| `<htmlpress-
|
|
155
|
-
| `<htmlpress-
|
|
156
|
-
| `<htmlpress-
|
|
157
|
-
| `<
|
|
158
|
-
| `<htmlpress-soundcloud>` + `<a href>` | a SoundCloud player for the linked track |
|
|
159
|
-
| `<htmlpress-mermaid>` + `<pre>` | a Mermaid diagram from the source in `<pre>` (escape `<` and `&`) |
|
|
193
|
+
| Element | Use |
|
|
194
|
+
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| `<htmlpress-callout type="…" title="…">` | a note; `type` is `info` (default), `note`, `tip`, `warning`, `danger` |
|
|
196
|
+
| `<htmlpress-cards>` + `<htmlpress-card title href icon>` | cards in two columns; `title` is the heading, `href` links the whole card, `icon` leads it |
|
|
197
|
+
| `<htmlpress-tabs sync="…">` + `<htmlpress-tab title>` | tabs, one per `<htmlpress-tab>`; tabs sharing `sync` switch together |
|
|
198
|
+
| `<h3 data-step>` | a numbered step, counted through the page; kept out of the TOC |
|
|
199
|
+
| `<htmlpress-badge variant="…">` | an inline label; `variant` `secondary`/`outline`/`positive`/`warning`/`destructive`, accent without it |
|
|
200
|
+
| `<htmlpress-filetree>` + nested `<ul>` | a file tree; an `<li>` holding a `<ul>` is a folder |
|
|
201
|
+
| `<htmlpress-icon name="…">` | an inline Lucide icon; names at htmlpress.dev/authoring/rich-elements/#icons |
|
|
202
|
+
| `<htmlpress-button href label variant="…">` | a call-to-action link; `variant` `secondary`/`outline`/`ghost`/`link`/`positive`/`warning`/`destructive`, `size` `sm`/`lg` |
|
|
203
|
+
| `<htmlpress-package-tabs>` + `<pre><code>` | one `npm`/`npx` command, built into npm, pnpm, yarn and bun tabs |
|
|
204
|
+
| `<htmlpress-terminal title="…">` + `<pre>` | terminal output: `<kbd>` command, `<samp>` output, `<ins>`/`<del>`/`<mark>` colours |
|
|
205
|
+
| `<htmlpress-video type="youtube" url>` | a YouTube video player for the video at `url` |
|
|
206
|
+
| `<htmlpress-audio type="soundcloud" url>` | a SoundCloud player for the track at `url` |
|
|
207
|
+
| `<pre><code class="language-mermaid">` | a Mermaid diagram from the source in the block (escape `<` and `&`) |
|
|
160
208
|
|
|
161
209
|
## Verification
|
|
162
210
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: htmlpress-configuration
|
|
3
|
-
description: Use when editing htmlpress.yaml — site metadata, base, include/exclude globs, code themes, sections (blog, changelog, custom), links, languages, versions, patches, head tags, agent skills, content signals
|
|
3
|
+
description: Use when editing htmlpress.yaml — site metadata, base, include/exclude globs, code themes, sections (blog, changelog, custom), links, languages, versions, patches, head tags, agent skills, content signals, the edit link and textlane plugins.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Htmlpress Configuration
|
|
@@ -35,6 +35,9 @@ exclude: [docs/includes/**]
|
|
|
35
35
|
codeThemeLight: catppuccin-latte
|
|
36
36
|
codeThemeDark: catppuccin-mocha
|
|
37
37
|
edit: https://github.com/acme/acme/edit/main/
|
|
38
|
+
plugins:
|
|
39
|
+
md: [{ name: md.shiftHeading, options: { shift: 1 } }]
|
|
40
|
+
html: [html.externalLinks]
|
|
38
41
|
links:
|
|
39
42
|
- { title: GitHub, url: https://github.com/acme/acme, position: header, icon: github }
|
|
40
43
|
sections:
|
|
@@ -53,12 +56,18 @@ head:
|
|
|
53
56
|
- `title`, `description`, `logo`, `favicon` (URLs) and `banner` (HTML above the header).
|
|
54
57
|
- `breadcrumbs` — `false` hides the folder trail above every page; default `true`, and a
|
|
55
58
|
page's `<meta name="breadcrumbs">` overrides it.
|
|
56
|
-
- `include` — globs of the `.html` files that become pages, default `**/*.html
|
|
57
|
-
a glob's base, its folders before the first wildcard, are read, and they are served without it:
|
|
59
|
+
- `include` — globs of the `.html` and `.md` files that become pages, default `**/*.html` and
|
|
60
|
+
`**/*.md` (a `README.md` too: exclude what is not a page). Only files under a glob's base, its folders before the first wildcard, are read, and they are served without it:
|
|
58
61
|
`docs/**/*.html` serves `docs/guide.html` at `/guide.html`. Other files there are copied as-is.
|
|
59
62
|
- `exclude` — globs left out of the build: partials for includes, drafts.
|
|
60
63
|
- `codeThemeLight`, `codeThemeDark` — the code block themes, by Shiki theme name.
|
|
61
64
|
- `edit` — a URL prefix for an "Edit on GitHub" link.
|
|
65
|
+
- `plugins` — textlane plugins added to the page pipeline, as Livemark's: `md` on a Markdown
|
|
66
|
+
page's tree after its directives, before heading ids and components; `html` on every page's
|
|
67
|
+
tree before heading ids. An entry is a name or `{ name, options }`. A plugin htmlpress already
|
|
68
|
+
runs (`md.gfm`, `html.slug`) is that plugin reconfigured, its options merged, not a second
|
|
69
|
+
run; an unknown name, or one whose tree does not fit the hook (`md.toHtml` at `html`), fails
|
|
70
|
+
the build.
|
|
62
71
|
|
|
63
72
|
## Sections
|
|
64
73
|
|
|
@@ -121,6 +130,7 @@ misspelt key fails here with its name.
|
|
|
121
130
|
## References
|
|
122
131
|
|
|
123
132
|
- Configuration: https://htmlpress.dev/customization/configuration-file/
|
|
133
|
+
- Plugins: https://htmlpress.dev/customization/plugins/
|
|
124
134
|
- Sections: https://htmlpress.dev/customization/article-sections/
|
|
125
135
|
- Translations: https://htmlpress.dev/customization/translations/
|
|
126
136
|
- Versioning: https://htmlpress.dev/customization/versioning/
|
|
@@ -63,12 +63,13 @@ upgrade it misses the new defaults: escape only what you change.
|
|
|
63
63
|
|
|
64
64
|
`layout.html` is plain HTML: htmlpress fills its `<head>` and replaces `<htmlpress-content>`,
|
|
65
65
|
`<htmlpress-brand>`, `<htmlpress-banner>`, `<htmlpress-nav>`, `<htmlpress-links>`,
|
|
66
|
-
`<htmlpress-breadcrumbs>`, `<htmlpress-toc>`, `<htmlpress-pager>`, `<htmlpress-edit>`,
|
|
66
|
+
`<htmlpress-breadcrumbs>`, `<htmlpress-page-toc>`, `<htmlpress-pager>`, `<htmlpress-edit>`,
|
|
67
67
|
`<htmlpress-toolbar>`, `<htmlpress-footer>`, `<htmlpress-language>` (the language picker) and
|
|
68
68
|
`<htmlpress-skip>` at build time, every string in the page's language. The interactive ones,
|
|
69
69
|
`<htmlpress-nav-toggle>`, `<htmlpress-search>`, `<htmlpress-theme-toggle>`, `<htmlpress-toc-bar>`
|
|
70
70
|
(the phone's contents bar), `<htmlpress-shortcuts>` (the keyboard shortcuts menu, listing every key and disabling the ones no
|
|
71
|
-
control on the page announces with `aria-keyshortcuts
|
|
71
|
+
control on the page announces with `aria-keyshortcuts`, and `H`/`L` without the head's `<link rel="prev">`/`rel="next"`, which
|
|
72
|
+
`scripts/keys.js` follows across sections, from the home page on) and `<htmlpress-back-to-top>`, run in the browser; the first three get their button at build time,
|
|
72
73
|
so the header is whole on its first frame. A head script sets `data-scripted` on `<html>`:
|
|
73
74
|
without it those buttons stay hidden, so style anything that needs scripts under
|
|
74
75
|
`:root[data-scripted]`. An element with nothing to show is removed. The theme toggle, the
|
|
@@ -126,6 +127,11 @@ the folder:
|
|
|
126
127
|
- To restyle a component from an outer one, beat its `:scope`: write `:scope htmlpress-header`,
|
|
127
128
|
not a bare `htmlpress-header`, which loses on specificity.
|
|
128
129
|
- Use tokens inside your CSS (`var(--htmlpress-muted)`) so dark mode keeps working.
|
|
130
|
+
- Every `<pre><code>` is highlighted by Shiki at build time, one without a language as plain
|
|
131
|
+
`text`: a component coloring its own code meets `pre.shiki` with an inline background, a
|
|
132
|
+
surface background forced with `!important`, and spans already inside. To color it
|
|
133
|
+
yourself, drop the `shiki` class and `style` from the `pre`, or dark mode's `.shiki span`
|
|
134
|
+
rule repaints every token one color.
|
|
129
135
|
|
|
130
136
|
## Verification
|
|
131
137
|
|
|
@@ -48,17 +48,17 @@ folder named after it (`image-quality.html` and `image-quality/`).
|
|
|
48
48
|
- **Metas**: `<title>`, `description` (what a reader learns, in one line), `date` (when the
|
|
49
49
|
content was last true) and `order` for the pages a newcomer should read first.
|
|
50
50
|
- **Lead with the answer.** The paragraph under the `<h1>` gives the conclusion or the
|
|
51
|
-
recommendation; the evidence follows. Headline numbers go in an `htmlpress-
|
|
51
|
+
recommendation; the evidence follows. Headline numbers go in an `htmlpress-cards` of
|
|
52
52
|
`htmlpress-card`s right after it.
|
|
53
53
|
- **Numbers carry their date and source**, near the top: a register goes stale, and the reader
|
|
54
54
|
must see when it was measured and from where. Cite each source with a link.
|
|
55
55
|
- **Statuses are badges** with one fixed meaning per site: `success` decided or done, `warning`
|
|
56
56
|
a call still to confirm, `danger` open or blocked. Say so in a legend if a page uses them.
|
|
57
57
|
- **Tables hold short cells.** A table never wraps a cell, so a row that needs prose becomes a
|
|
58
|
-
`<dl>`: the item as `<dt>`, its reasons as `<dd>`.
|
|
58
|
+
`<dl>`: the item as `<dt>`, its reasons as `<dd>`. A table with a `<thead>` sorts by a click on a header.
|
|
59
59
|
- **Diagrams are inline SVG**, drawn for the real structure, in a `<figure>` with a
|
|
60
60
|
`<figcaption>`, styled by a page `<style>` scoped to that figure with `--htmlpress-*` tokens
|
|
61
|
-
only, so it follows light and dark. `
|
|
61
|
+
only, so it follows light and dark. a `language-mermaid` code block for a quick flow.
|
|
62
62
|
|
|
63
63
|
## A decision log
|
|
64
64
|
|