Publish Markdown with the LitPage CLI

Use the LitPage CLI to publish a Markdown article from your computer to the Blog on an existing LitPage site. You will create a local file, save it as a draft, review it in LitPage, then publish and check the public result. The commands below use @litpage/cli version 0.6.7.

Prepare your workspace and choose a site

Use Node.js 18 or later and an existing LitPage account, workspace and site. Create a workspace API key in LitPage with access to the site you intend to update. Provide the key to your shell as LITPAGE_WORKSPACE_KEY through your local secret manager or environment setup. Keep it out of the Markdown file, shared configuration, and logs.

npx @litpage/[email protected] doctor
npx @litpage/[email protected] site list

doctor checks the key and reports which sites it can access. site list gives you the accessible destinations. Find the site you want and copy its subdomain. For example, the subdomain for studio-notes.lit.page is studio-notes. In the steps below, your-site stands for the actual subdomain you selected.

If your key can access multiple sites, set subdomain in the file so the destination is explicit. A command-line --subdomain overrides the file. The CLI may use configuration or environment defaults when the file omits it. Use the same target for every step of this exercise.

Create a Markdown file

From a project directory, generate a starter file.

npx @litpage/[email protected] content template ./post.md

Open post.md and replace the sample with the fictional article below. Substitute your actual site subdomain before running apply.

---
title: Studio field notes
slug: studio-field-notes
subdomain: your-site
type: BLOG
language: EN
excerpt: A short update from the ceramics studio.
author:
  name: Studio Editorial
updateReason: Initial draft
---

This week we compared two bowl shapes for our next tableware collection.

## What we checked

We tested how each bowl felt when held and how the glazes looked in daylight.

The YAML between the two --- lines identifies the article and the destination. Keep the slug stable if you want to update the same article later. Use a slug that is unused on your site for this first example. The title becomes the article title, so begin the body with the introduction and use lower-level headings for sections.

Save a draft and review it

npx @litpage/[email protected] apply ./post.md

On success the CLI prints JSON to standard output. Open the target site in LitPage and find Studio field notes in Blogs. Check that the slug is studio-field-notes and review the excerpt and article. Open its authorized preview to check the heading, paragraph, and links in the site layout. If the preview fails, keep the article in draft while you check the site, language, and preview status in LitPage.

apply saves a draft. When you edit an already published article, the existing public version stays visible. For that update the output includes meta.draftUpdated and meta.publicSnapshotUnchanged.

Publish and check the public article

After review, run the publish command with the file you reviewed.

npx @litpage/[email protected] publish ./post.md

publish sends the current local file and makes that revision public. If you changed the article in LitPage after apply, copy the intended changes into the local file and review it again before running publish. Check the success JSON, then open the published article from Blogs in LitPage. Confirm the expected host, language, slug, article title and latest paragraph. Use the actual public link shown for your site, since the language prefix can depend on the site’s settings.

To revise the same article later, keep its subdomain and slug, update the Markdown body, and repeat apply, review, and publish. Check the public page after publishing to confirm that readers see the new revision.

Recover from common errors

What you see	What to check
The key fails or the site is missing	Run `doctor`, confirm the environment variable is available in that shell, and verify the key belongs to the intended workspace and can access the site.
The target is ambiguous	Check `site list`, then set `subdomain` in the file. If you pass `--subdomain`, check its value because it overrides the file.
The file or slug cannot be read	Confirm the file path and both `---` delimiters. Keep a nonempty `slug` in the frontmatter or pass `--slug` intentionally. Use `apply --help` to check supported arguments.
You still see the old public article	Confirm whether the last command was `apply` or `publish`. Check the target site and slug, and open the public URL after a successful publish.

Errors are JSON on standard error. Read the message and verify the article in LitPage before retrying a publish with an uncertain result. Keep the same site and slug when retrying an update.

See the LitPage CLI page for the quick workflow or open the npm package for the command reference.