Creating a new site
Status
This record describes the design of heine new and its starting site. The
existing starter site remains the larger
example of Heine's features.
Purpose
A person who has installed Heine should be able to create a small site and start editing it immediately. The site should also be ready for common publishing needs as it grows. Its default pages should stay short and useful; they do not need to demonstrate every feature its templates support.
Command
heine new my-site
cd my-site
heine serveThe command requires a destination path, creates a new site there, and prints the next steps. It works offline and does not ask questions, run a build, initialize Git, fetch files, or execute external renderers. The generated files are determined by the Heine version: their relative paths and bytes do not depend on the destination name, current time, or runtime environment.
The parent directory must already exist and the destination must not exist,
including when the destination is . or an empty directory. Heine reports
filesystem failures with the affected path and does not overwrite or merge
existing files. Creation must not follow a destination symlink. Claim the new
directory with one exclusive creation operation; that operation is the
authoritative existence check. Create its files without replacing existing
entries.
The implementation must account for a destination appearing while the command
runs. Existing parent directories may be reached through symlinks; Heine does
not claim protection against a concurrently hostile filesystem.
On failure, Heine attempts to remove only entries it created for this attempt, in reverse order, using non-recursive operations. It must not recursively remove unrecognized content. Cleanup is best effort when another process changes the filesystem: a recorded path alone does not prove that the same entry is still there. If Heine cannot safely identify or remove an entry, it leaves it in place and reports what remains.
new does not discover a site root. Reject --root and build or serve options
for this command rather than ignoring them. Print the created path on its own
line and describe the next steps in words. Do not print a shell command with
quoting that may be wrong for the user's shell or destination path.
Interruption or forced termination can leave a partial site; automatic cleanup
is best effort for failures Heine handles.
The site
The repository's top-level new-site/ directory is an ordinary, buildable
Heine site and the canonical source for the generated files. The command embeds
its authored inputs in the executable, so an installed binary needs neither the
repository nor a network connection. The directory does not select or contain
a kit. Templates, configuration, messages, styles, scripts, and content belong
to the generated site and can be edited directly. Include a .gitignore for
public/ and .heine/; the command does not initialize a repository.
A generated site is an independent snapshot of the inputs shipped with that Heine release. Heine does not synchronize or upgrade its files afterward. Authors maintain their own copies and use the changelog to follow any future configuration or template migrations.
The initial navigation leads to a home page, About, a blog with two short posts, and search. The profile illustration appears naturally in the layout. Sample identity and prose should make replacement straightforward, without implying a real author or publication history. There is one English locale; reader-facing interface text lives in Fluent. Locale-aware formatting remains available, and the site can be extended with other locales without extracting template text. It does not claim to supply translations.
The stylesheet uses system fonts and follows the system light or dark color scheme. The site ships neither a font nor a math example. Built-in MathML is available when an author adds mathematics; its appearance depends on the reader's browser and available fonts. The only authored image is the supplied profile SVG. The site also contains the CSS and JavaScript needed for its layout and search.
Capabilities without showcase content
Configure the blog collection, tags, search, and listing pagination so the two posts form a working site. Posts are ordered by publication date and show their localized dates. A second pagination page need not exist until there are enough posts. Supply Series listing templates, page navigation, and messages, but do not configure a Series or generate an empty Series index. The article layout includes a direct Series navigation hook, and the README explains how to configure a Series when the author needs one. An unconfigured site has no empty navigation or Series links.
Enable built-in MathML and ordinary Markdown footnotes. Page templates support a selected table of contents and Series navigation. The new site does not include citation or margin-footnote configuration, templates, or styles. Authors can add those features later using the relevant guides. Calls that depend on a page or site setting are conditional, so an ordinary post builds without those settings.
Do not invent a deployment origin merely to enable features that require an absolute URL. The README explains that canonical URLs need an origin, and that a sitemap and feed also require their own configuration.
Assets and maintenance
Project-authored, copyable new-site/ material is available under MIT;
separately declared resources retain their own licenses. This includes the
supplied profile.svg, whose copyright notice must identify its creator
truthfully. Preserve the applicable notices and license texts with the source
and generated site, and update the repository's licensing documentation when
the site is added. These terms cover the supplied material, not content an
author adds later. Apply Heine's normal asset licensing rules to the
illustration, CSS, and JavaScript. Do not alter the SVG merely to make it
match the site's palette without a separate reason.
Place the MIT text in LICENSES/MIT.txt, and explain which supplied files it
covers in the site README or a scoped LICENSING.md. Do not add a root
LICENSE that appears to set terms for content the author adds later.
The search client is maintained in
starter-site/kits/starter/assets/js/search.js. new-site/ contains a full
copy with its existing ownership comment. A test checks that the files match;
updates copy the whole file. No synchronization script or runtime kit
dependency is needed. The new site owns its other files. Its CSS can adapt
tested starter-site patterns, particularly for search, without requiring the
two stylesheets or templates to remain identical. The copied client's MIT
terms and any separately declared exceptions remain part of the site's
licensing information.
The embedded files come from a deliberate, reviewable inventory of authored
inputs, including dotfiles and license declarations. Directory traversal alone
must not silently include unrelated local files, caches, or generated output.
The inventory and embedding process must work when building from a crate
package without Git or a repository checkout. Preserve file bytes; the command
does not substitute site names or timestamps. Missing or duplicate inventory
entries are errors. A repository check compares the inventory with the intended
source files in both directions, excluding known generated directories such as
public/ and .heine/; ordinary packaged builds use the inventory without
Git. Only inventoried files and their parent directories are created; empty
source directories are not preserved. Heine creates ordinary files and
directories with platform filesystem APIs and permissions. It does not copy
executable bits or other source metadata.
The generated site includes a README that explains how to add and date a post and identifies the editable content, templates, assets, and Fluent messages. It explains Series setup, the site origin and the separate configuration needed for a sitemap or feed, licensing of the supplied material, and the independent-snapshot maintenance model.
Implementation and acceptance checks
- Build
new-site/directly with Heine and build a newly created site using the public command. The created files match the intended source files, including licensing declarations, without generated output or caches. Two destinations receive identical relative paths and bytes. A repeated invocation fails without changing the existing site. - Inspect the crate's package contents and test a binary built from the package outside the repository. It creates a site that builds, including dotfiles and license declarations. The embedded file set contains exactly the inventoried files and does not require Git at build or runtime.
- Keep project-authored new-site text at LF line endings across checkouts; choose and verify suitable repository attributes and embedding rules.
- Check existing destinations, missing or read-only parents, trailing separators, symlinks, platform-specific invalid names, case-insensitive collisions, creation failures, and cleanup failures without overwriting user files. Diagnostics identify the path and underlying failure.
- Exercise templates with temporary fixture content for pagination, tags, Series, table of contents, ordinary footnotes, and MathML. The shipped posts remain free of artificial demonstrations. Check both enabled and absent settings, including an ordinary post with no table of contents or Series.
- Check the generated README's configuration examples against a copy of the site, including Series setup and its generated index.
- Check responsive layout, focus visibility, and light and dark contrast in a browser at mobile and desktop sizes. Check the prepared presentations with temporary content, including print behavior. Check the search template against the client contract and exercise a search in the browser.
- Document the command and its destination rules. Include the site README topics described above: editable files, localization, Series setup, site origin, sitemap and feed configuration, licensing, and snapshot maintenance. Update the CLI reference and changelog when the feature is implemented.
Boundaries
This command creates one project-owned starting site. It is not a kit installer, a remote template catalog, an interactive site builder, or a general content-generation command. The existing starter site remains a separate, more comprehensive example.