gethtmlpress 0.1.0 → 0.2.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.
Files changed (6) hide show
  1. package/package.json +7 -7
  2. package/skills/htmlpress-authoring/SKILL.md +15 -9
  3. package/skills/htmlpress-configuration/SKILL.md +9 -6
  4. package/skills/htmlpress-customization/SKILL.md +8 -4
  5. package/skills/htmlpress-deployment/SKILL.md +4 -5
  6. package/skills/htmlpress-landing/SKILL.md +4 -3
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gethtmlpress",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Turn a folder of HTML pages into a site: one layout, one theme, live reload, made for agents",
5
5
  "keywords": [
6
6
  "agents",
@@ -30,11 +30,11 @@
30
30
  "node": ">=20"
31
31
  },
32
32
  "optionalDependencies": {
33
- "@htmlpress/linux-x64": "0.1.0",
34
- "@htmlpress/linux-arm64": "0.1.0",
35
- "@htmlpress/darwin-x64": "0.1.0",
36
- "@htmlpress/darwin-arm64": "0.1.0",
37
- "@htmlpress/win32-x64": "0.1.0",
38
- "@htmlpress/win32-arm64": "0.1.0"
33
+ "@htmlpress/linux-x64": "0.2.0",
34
+ "@htmlpress/linux-arm64": "0.2.0",
35
+ "@htmlpress/darwin-x64": "0.2.0",
36
+ "@htmlpress/darwin-arm64": "0.2.0",
37
+ "@htmlpress/win32-x64": "0.2.0",
38
+ "@htmlpress/win32-arm64": "0.2.0"
39
39
  }
40
40
  }
package/skills/htmlpress-authoring/SKILL.md CHANGED
@@ -35,12 +35,15 @@ The config keys are in `htmlpress-configuration`; a different look in `htmlpress
35
35
  - `<meta name="order" content="N">` (an integer) sorts the navigation, lower first.
36
36
  `index.html` always comes first; unordered pages follow by path, then negative orders
37
37
  (`-1` pins a page last).
38
- - Other `<head>` tags (`<link>`, `<style>`, `<script>`) are kept and added after the theme.
38
+ - Other `<head>` tags (`<link>`, `<style>`, `<script>`) are kept and added after the theme; a
39
+ fragment's are the ones before its first content, as a browser reads them.
39
40
  - The navigation nests pages by folder at any depth (`guides/cli/…` inside `guides/…`), each
40
- group named by its `index.html`, whose title links to it.
41
- - Pages are written to the same path, so link between them with relative hrefs
42
- (`guides/build.html`). Images and other files are copied as-is; a relative `src`,
43
- `srcset` or `poster` resolves from the source file, even when the page moves.
41
+ group named by its `index.html`, whose title links to it and whose `order` places the folder.
42
+ - Each page is served at its own folder URL: `guides/build.html` at `/guides/build/`,
43
+ `guides/index.html` at `/guides/`. Link to the page file (`guides/build.html`, relative or
44
+ root-relative) or to its URL: a link naming a page's file becomes its URL. Images and other
45
+ files are copied as-is; a relative `href`, `src`, `srcset` or `poster` resolves from the
46
+ source file, even when the page moves.
44
47
  - A root `404.html` is the not-found page, kept out of the navigation; without one a built-in
45
48
  is used.
46
49
 
@@ -57,6 +60,7 @@ The config keys are in `htmlpress-configuration`; a different look in `htmlpress
57
60
  | `path` (`/start/`) | serves the page at another URL |
58
61
  | `sidebar` (`false`) | built, not listed |
59
62
  | `toc` (`false`) | no table of contents |
63
+ | `breadcrumbs` (`false` / `true`) | hides or shows the folder trail, over the config's |
60
64
  | `layout` (`<name>`) | another layout, from `htmlpress-customization` |
61
65
  | `language` (`<code>`) | marks the page a translation |
62
66
  | `source-url`, `source-action` (`view`) | the page's source link |
@@ -68,7 +72,8 @@ A file that cannot carry metas, such as a `README.md`, gets them from `patches`
68
72
  With `languages` in the config, a translation is `page.<code>.html` beside `page.html`, or a
69
73
  file with `<meta name="language" content="<code>">`. It pairs with the original by URL below the
70
74
  language prefix, so a renamed one needs the same `<meta name="path">`. Untranslated pages stay
71
- listed in every language with a badge and link to the original.
75
+ listed in every language with a badge and link to the original. Without a translated home,
76
+ `/<code>/` redirects to the language's first page.
72
77
 
73
78
  ## Headings
74
79
 
@@ -124,7 +129,7 @@ component, not bare text.
124
129
  | `<htmlpress-file-tree>` + nested `<ul>` | a file tree; an `<li>` holding a `<ul>` is a folder |
125
130
  | `<htmlpress-table>` + `<table>` | a table sorted by a click on a `<thead>` header |
126
131
  | `<htmlpress-zoom>` + `<img>` | an image that opens full screen on click |
127
- | `<htmlpress-icon name="…">` | an inline Lucide icon; names at htmlpress.dev/authoring/rich-elements.html#icons |
132
+ | `<htmlpress-icon name="…">` | an inline Lucide icon; names at htmlpress.dev/authoring/rich-elements/#icons |
128
133
  | `<htmlpress-button type="…">` + `<a>` | a call-to-action link; `type` `secondary`/`outline`/`ghost`/`link`/`positive`/`warning`/`destructive`, `size` `sm`/`lg` |
129
134
  | `<htmlpress-package-tabs>` + `<pre><code>` | one `npm`/`npx` command, built into npm, pnpm, yarn and bun tabs |
130
135
  | `<htmlpress-terminal title="…">` + `<pre>` | terminal output: `<kbd>` command, `<samp>` output, `<ins>`/`<del>`/`<mark>` colours |
@@ -137,6 +142,7 @@ component, not bare text.
137
142
  ```sh
138
143
  htmlpress build <root> --json # {"output": "...", "pages": N, "files": N}; errors on stderr
139
144
  htmlpress start <root> # http://localhost:8000 (or the next free port to 8009); --host for the network
145
+ htmlpress start <root> --json # {"url": "...", "network": []} on one line once serving
140
146
  htmlpress --llms # every command's input and output schema
141
147
  ```
142
148
 
@@ -147,5 +153,5 @@ For a visual check, run `start` and open the page; look at it narrow as well as
147
153
  ## References
148
154
 
149
155
  - Pages: https://htmlpress.dev/authoring/
150
- - Components: https://htmlpress.dev/authoring/rich-elements.html
151
- - Code blocks: https://htmlpress.dev/authoring/code-blocks.html
156
+ - Components: https://htmlpress.dev/authoring/rich-elements/
157
+ - Code blocks: https://htmlpress.dev/authoring/code-blocks/
package/skills/htmlpress-configuration/SKILL.md CHANGED
@@ -29,6 +29,7 @@ description: Acme's docs.
29
29
  logo: /logo.svg
30
30
  favicon: /favicon.svg
31
31
  banner: <a href="/blog/">We shipped 2.0</a>
32
+ breadcrumbs: false
32
33
  include: [docs/**/*.html]
33
34
  exclude: [docs/includes/**]
34
35
  codeThemeLight: catppuccin-latte
@@ -50,6 +51,8 @@ head:
50
51
  - `base` — a sub-path such as `/repo/`. Root-relative URLs get it as a prefix, so write them
51
52
  without it.
52
53
  - `title`, `description`, `logo`, `favicon` (URLs) and `banner` (HTML above the header).
54
+ - `breadcrumbs` — `false` hides the folder trail above every page; default `true`, and a
55
+ page's `<meta name="breadcrumbs">` overrides it.
53
56
  - `include` — globs of the `.html` files that become pages, default `**/*.html`. Only files under
54
57
  a glob's base, its folders before the first wildcard, are read, and they are served without it:
55
58
  `docs/**/*.html` serves `docs/guide.html` at `/guide.html`. Other files there are copied as-is.
@@ -93,7 +96,7 @@ section.
93
96
  ## Patches
94
97
 
95
98
  Each patch is a `file` and an `article` of metas (`title`, `label`, `description`, `icon`,
96
- `order`, `path`, `sidebar`, `toc`, `image`, `author`, `date`, `tags`, `sourceUrl`,
99
+ `order`, `path`, `sidebar`, `breadcrumbs`, `toc`, `image`, `author`, `date`, `tags`, `sourceUrl`,
97
100
  `sourceAction`), set without touching the file; a patched `.md` file such as `README.md` is
98
101
  published as a page. A patched path outside the project, through a symlink or into a dot-folder is refused.
99
102
 
@@ -117,8 +120,8 @@ misspelt key fails here with its name.
117
120
 
118
121
  ## References
119
122
 
120
- - Configuration: https://htmlpress.dev/customization/configuration-file.html
121
- - Sections: https://htmlpress.dev/customization/article-sections.html
122
- - Translations: https://htmlpress.dev/customization/translations.html
123
- - Versioning: https://htmlpress.dev/customization/versioning.html
124
- - Patches: https://htmlpress.dev/customization/article-patches.html
123
+ - Configuration: https://htmlpress.dev/customization/configuration-file/
124
+ - Sections: https://htmlpress.dev/customization/article-sections/
125
+ - Translations: https://htmlpress.dev/customization/translations/
126
+ - Versioning: https://htmlpress.dev/customization/versioning/
127
+ - Patches: https://htmlpress.dev/customization/article-patches/
package/skills/htmlpress-customization/SKILL.md CHANGED
@@ -67,10 +67,14 @@ upgrade it misses the new defaults: escape only what you change.
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
- (the phone's contents bar and sheet) and `<htmlpress-back-to-top>`, run in the browser; the first three get their button at build time,
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`) and `<htmlpress-back-to-top>`, run in the browser; the first three get their button at build time,
71
72
  so the header is whole on its first frame. A head script sets `data-scripted` on `<html>`:
72
73
  without it those buttons stay hidden, so style anything that needs scripts under
73
- `:root[data-scripted]`. An element with nothing to show is removed.
74
+ `:root[data-scripted]`. An element with nothing to show is removed. The theme toggle, the
75
+ language picker and the sidebar's section picker drop down from `56rem` up and, like the
76
+ contents bar, open an `<htmlpress-sheet>` on a phone: one bottom sheet the scripts append to
77
+ `<body>`, so escape `components/sheet/sheet.css` to restyle every sheet at once.
74
78
 
75
79
  Pages crossfade only their content: `<htmlpress-header>` and `<htmlpress-sidebar>` carry the
76
80
  view transition names `htmlpress-header` and `htmlpress-sidebar`, and a hovered link's page is
@@ -131,5 +135,5 @@ at once.
131
135
 
132
136
  ## References
133
137
 
134
- - Overriding: https://htmlpress.dev/customization/overriding-escaping.html
135
- - Layouts: https://htmlpress.dev/customization/custom-routes.html
138
+ - Overriding: https://htmlpress.dev/customization/overriding-escaping/
139
+ - Layouts: https://htmlpress.dev/customization/custom-routes/
package/skills/htmlpress-deployment/SKILL.md CHANGED
@@ -24,7 +24,8 @@ htmlpress preview # serves the production build locally, the way a host
24
24
  htmlpress clear # removes .htmlpress/build
25
25
  ```
26
26
 
27
- The output is `.htmlpress/build/`: an `.html` per page at its source's path, `404.html`,
27
+ The output is `.htmlpress/build/`: an `index.html` per page in its own folder
28
+ (`guides/build.html` at `guides/build/index.html`), `404.html`,
28
29
  `robots.txt`, `_headers`, a Markdown copy of each page and `llms.txt` for agents, the skills
29
30
  under `.well-known/agent-skills/`, the theme under `_htmlpress/`, and every other project file.
30
31
  With `site` set it adds `sitemap.xml`. Never edit the output: every build replaces it.
@@ -41,7 +42,7 @@ With `site` set it adds `sitemap.xml`. Never edit the output: every build replac
41
42
 
42
43
  | Host | Setup |
43
44
  | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
- | Cloudflare Workers | `wrangler.jsonc`: `assets.directory: ".htmlpress/build"`, `html_handling: "none"`, `not_found_handling: "404-page"`; `npx wrangler deploy` |
45
+ | Cloudflare Workers | `wrangler.jsonc`: `assets.directory: ".htmlpress/build"`, `not_found_handling: "404-page"`; `npx wrangler deploy` |
45
46
  | GitHub Pages | `site: https://<user>.github.io`, `base: /<repo>/`; `npx gh-pages -d .htmlpress/build --nojekyll --dotfiles`, or the Pages actions uploading `.htmlpress/build` |
46
47
  | Vercel | `vercel.json`: `"framework": null`, `"buildCommand": "npx gethtmlpress build"`, `"outputDirectory": ".htmlpress/build"` |
47
48
  | Netlify | `netlify.toml`: `[build] command = "npx gethtmlpress build"`, `publish = ".htmlpress/build"` |
@@ -52,8 +53,6 @@ With `site` set it adds `sitemap.xml`. Never edit the output: every build replac
52
53
  ## Rules of thumb
53
54
 
54
55
  - Point the host's not-found page at `404.html`, so unknown paths keep the site's layout.
55
- - Keep `html_handling: "none"` on Cloudflare: its default redirects `/guide.html` to `/guide`,
56
- away from the URLs htmlpress links to.
57
56
  - Keep `--nojekyll` and `--dotfiles` on a GitHub Pages branch deploy: Jekyll drops the
58
57
  `_htmlpress/` theme, and without dot-files `.well-known/` is lost.
59
58
  - Files under `_htmlpress/` keep their names between builds: cache them briefly or invalidate
@@ -69,4 +68,4 @@ styles load and links keep the prefix.
69
68
  ## References
70
69
 
71
70
  - Deployment: https://htmlpress.dev/deployment/
72
- - Static hosting: https://htmlpress.dev/deployment/static-hosting.html
71
+ - Static hosting: https://htmlpress.dev/deployment/static-hosting/
package/skills/htmlpress-landing/SKILL.md CHANGED
@@ -93,7 +93,8 @@ project has something real to say in; three strong ones beat seven thin ones.
93
93
 
94
94
  ## Rules of thumb
95
95
 
96
- - Links are root-relative (`/introduction.html`); `base` is added at build time.
96
+ - Links are root-relative (`/introduction/`, or the file, `/introduction.html`); `base` is added
97
+ at build time.
97
98
  - Keep the landing out of the sidebar (`sidebar` false) but give it a real `<title>` and
98
99
  `description`: it is the site's social preview.
99
100
  - Every component must read well with its JS off: the slides are already in the HTML.
@@ -107,5 +108,5 @@ be reachable by keyboard.
107
108
 
108
109
  ## References
109
110
 
110
- - Layouts: https://htmlpress.dev/customization/custom-routes.html
111
- - Overriding: https://htmlpress.dev/customization/overriding-escaping.html
111
+ - Layouts: https://htmlpress.dev/customization/custom-routes/
112
+ - Overriding: https://htmlpress.dev/customization/overriding-escaping/