# First site

Build a small Field Guide using Markdown files. By the end, you will have a section landing page, a practical guide with a checklist and command block, a searchable reader, and a clear boundary between source and generated output. The optional browser editor is not required for this exercise.

# Before you begin

You need Node.js 24+, npm, Git and a terminal with write access to a new project folder. Verify node --version, npm --version and git --version. Install prerequisites using Windows macOS and Linux if a command is missing. An existing production site’s folders are not a safe scratch workspace.

If you already have a clean V2 checkout with dependencies installed, skip cloning. Otherwise:

git clone https://github.com/KineticEnforcer/MarkStackV2.git
cd MarkStackV2
npm ci

Keep package.json and package-lock.json together. npm ci is for installing a lockfile-defined dependency set, not for changing package versions. Record git rev-parse HEAD if you need to reproduce the build later. This guide is grounded in the pinned V2 revision named in Complete setup.

# 1. Establish the baseline

npm run build
npm run serve

The builder writes dist/; preview serves that directory on loopback, normally http://127.0.0.1:3000. Keep the server running while you inspect the included home page. Open a deep page and search for one of its headings. If the baseline is unstyled or search does not work, fix that before adding your content.

Opening HTML directly from the filesystem is not the same test. Use the served URL so root-relative CSS, scripts and the search index behave as they will on a host. Press Ctrl+C to stop the preview when needed; it does not delete source or output.

# 2. Create a section with an explicit landing page

Create content/guides/. In a Unix shell use mkdir -p content/guides; in PowerShell use New-Item -ItemType Directory -Path content/guides -Force. Create content/guides/_index.md in your text editor:

---
title: Guides
description: Practical steps for people using Field Guide.
---

# Guides

Start with the workstation check before following the team's project instructions.

- [Hello](/guides/hello/): verify your tools and record what worked.

_index.md is the landing page for a folder, not a normal leaf page. The folder’s title is part of child routes. Keep the title Guides while following this exercise so the link above matches the generated URL.

Do not copy the existing documentation into the new folder just to create volume. Begin with one useful task and make it complete enough that a reader can do it without asking you what a missing step means.

# 3. Add a complete first page

Create content/guides/hello.md:

---
title: Hello
description: Check the tools needed to build this documentation site.
---

# Hello

Use this check on a development machine before building Field Guide.
It checks installed tools; it does not install packages or change the machine.

## Check the tools

Open a terminal and run:

~~~bash
node --version
npm --version
git --version
~~~

Node must be version 24 or newer. npm and Git should print their installed versions.
If a command is missing, install that tool and reopen the terminal before repeating the check.

## Record the result

- [ ] Node prints a supported version.
- [ ] npm prints a version.
- [ ] Git prints a version.

These boxes are document content, not shared completion records.
Record your actual result in the team's chosen tracking system.

## Next step

Return to [Guides](/guides/) or build the site and inspect this page.

The ~~~ fences in this sample are Markdown code fences too. They let the complete file be shown inside an outer example fence without closing that example early. You can use ordinary triple backticks in your own file when writing directly.

Frontmatter is YAML between --- lines. The description supplies generated page-description metadata; it is not a separate indexed search field. The title determines display text, indexed title and the title-based route. Changing the filename alone is not a reliable way to control a route with an explicit title.

# 4. Rebuild and inspect the generated page

In the project terminal:

npm run build

Reload the running preview and visit /guides/hello/. You should see the Hello title, the Check the tools and Record the result headings, a code block with a Copy control, and a rendered checklist. Search for Check the tools; a heading result should lead into the page rather than only to its top.

If the builder reports a duplicate URL, do not edit generated HTML to conceal it. Look for two titles or folder paths that normalize to the same route. Choose distinct titles, rebuild and retest links. If the page is absent, confirm you saved it under the checkout’s content/, not another clone or dist/.

# 5. Make the identity your own

Edit siteconfig.json with valid JSON. For this exercise, change these existing values:

{
  "siteTitle": "Field Guide",
  "headerTitle": "Field Guide",
  "siteSubtitle": "Practical documentation kept in files.",
  "siteUrl": "https://docs.example.com",
  "baseUrl": ""
}

This is a fragment showing fields to change, not a command to discard the rest of your configuration. docs.example.com is an illustrative destination: replace it with your intended public URL before a real deployment. Keep baseUrl empty for a domain-root site. Subpath hosting needs a consistent base URL and separate link/asset checks.

Edit content/_index.md to introduce Field Guide and link to /guides/hello/. Preserve any existing content you still need. Put local images under static/images/ and use /images/your-file.png at a domain root. Review the public material before copying it there.

An optional editor can store runtime branding that takes precedence over file settings. If a file-based configuration change appears ignored, inspect the selected runtime data and Site settings instead of repeatedly changing the same JSON field.

# 6. Keep a fast but explicit writing loop

Use two terminals in the project directory:

# Terminal one
npm run watch

# Terminal two
npm run serve

Save Markdown, wait for a successful rebuild and refresh the browser. Watch mode tracks content, static assets and templates. Make an explicit build after changes to configuration or external data so you know the current settings were read. A browser refresh alone cannot turn changed source into new output.

WARNING A build clears its output directory before writing. Never select a content folder, private-data folder, project root or another valuable directory as --out.

# 7. Keep source, publish only output

Commit your intended Markdown, configuration and public media to your own source history. Do not treat dist/ as the only copy of your work: rebuilding overwrites it. Private editor data and backups stay outside the public upload.

To deploy, deliver the contents of dist/ to a static host with index.html at the upload root. Do not upload the whole checkout. See Static deployment and perform the same reader checks on the actual live URL.

# Common failures and how to check them

A build exits unsuccessfully for an invalid source or missing dependency. Diagnose its actual message before repeating it. Duplicate URL preflight protects the previous output from that particular collision; later failures in a normal build can leave incomplete output. Keep a previous checked build when continuity matters.

The finished exercise is a real file-based writing workflow. For browser writing, continue to Administrator and editor. For where each file belongs and what not to upload, read Project map.