Skip to content
Shane Docs

Install & Quick Start

Both tools (shane-new-post for blogs, shane-new-doc for docs sites) install the same way, just under a different package name. Both are shown explicitly below.

Section titled “Option 1: One-command installer (recommended)”

Same pattern as npm create astro@latest. Run this from the project root (where package.json lives):

Terminal window
# shane-new-post (for blogs)
npm create shane-new-post@latest


# shane-new-doc (for docs sites)
npm create shane-new-doc@latest

This handles everything automatically:

  1. Scans for scripts that would conflict with what this tool generates (new-post.js and common name variants), and asks before removing any.
  2. Detects the package manager in use (npm / pnpm / yarn) and installs the dependency with it.
  3. If the package manager skipped install-time scripts (common with newer pnpm), runs the setup manually so the install always finishes complete.

During setup you’re asked for a default author name (shane-new-post only — shane-new-doc has no author field, so it skips this: Starlight’s default docs schema has no author key, and writing one in would fail schema validation). Leave it blank to omit the field entirely. Once setup finishes, the project looks like this:

shane-new-post:

  • Directorysrc/
    • Directorycontent/
      • Directoryposts/
        • …
  • Directorypublic/
    • Directoryimg/
      • …
  • Directoryscripts/
    • new-post.js
  • .shane-new-post.json saved language + author choice
  • package.json

shane-new-doc:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • …
  • Directoryscripts/
    • new-doc.js
  • .shane-new-doc.json saved language choice (no author field)
  • package.json

pnpm new-post (or npm run new-post / yarn new-post) and pnpm new-doc (or npm run new-doc / yarn new-doc) are ready to use immediately.

Choosing a language

Section titled “Choosing a language”

Both packages ship English and Chinese prompts/messages in the same install — nothing extra to add. If the terminal is interactive and no language was specified up front, the installer asks once:

Select CLI language / 选择界面语言: (Use arrow keys)
❯ English
  简体中文

The choice is saved to .shane-new-post.json / .shane-new-doc.json in the project root and reused by every later new-post / new-doc run — it won’t ask again.

To skip the prompt, pass a --lang flag up front:

Terminal window
npm create shane-new-post@latest -- --lang=zh-cn
npm create shane-new-doc@latest -- --lang=zh-cn

--lang=en also works, and so do the shorthands --en / --zh / --zh-cn / --chinese / --english.

Full language-resolution order

Section titled “Full language-resolution order”

Every time new-post / new-doc runs, the language is resolved in this order — the first match wins:

  1. A flag on this exact command: --lang=en / --lang=zh-cn (or a shorthand like --zh-cn / --en). This always wins even if a language was already saved, so it works as a one-off override without touching the saved config.
  2. The SHANE_CLI_LANG environment variable — useful in CI, or for forwarding a choice to a spawned child process.
  3. The "lang" field already saved in .shane-new-post.json / .shane-new-doc.json — set once at install time, reused afterward.
  4. The OS/shell locale (Intl, then $LC_ALL / $LANG / $LANGUAGE) — used as a best-effort guess only when nothing above matched.
  5. English, as the last-resort fallback.

Only step 4 is a low-confidence guess with no explicit signal; steps 1–3 all reflect something explicitly set. To change the language later without re-running the installer, either edit the "lang" field in the saved config file directly, or pass --lang on a single new-post / new-doc invocation for a one-off override.

Option 2: Manual install

Section titled “Option 2: Manual install”

The package can also be added as a dependency directly, without the installer:

Terminal window
# shane-new-post (for blogs)
npm install -D shane-new-post


# shane-new-doc (for docs sites)
npm install -D shane-new-doc

Both languages are bundled in the same package — installing shane-new-post or shane-new-doc gives English and Chinese prompts either way. See Choosing a language above for how to pick one.

Verify the install

Section titled “Verify the install”

Whichever option you used, don’t just trust that it worked — check two things in the project root.

  1. A .shane-new-post.json (or .shane-new-doc.json) file exists at the project root, containing at least a saved "lang" field.
  2. package.json has a new-post (or new-doc) entry inside "scripts", pointing at the file that was generated under scripts/.

Most of the time both are already there and you can skip straight to shane-new-post Guide or shane-new-doc Guide. But some package managers — newer pnpm in particular — skip lifecycle scripts (postinstall) by default unless explicitly told otherwise, and a few CI/non-interactive installs run with --ignore-scripts set globally. In that situation the dependency gets added to package.json, but nothing under scripts/ is ever generated and the scripts entry is never injected. The one-command installer (npm create / pnpm create / yarn create) already re-checks for this and re-runs setup automatically when it detects that — see Installation Internals for exactly how. A manual install (Option 2 above) has no such fallback, so this is the case most likely to affect you.

If scripts/new-post.js (or new-doc.js) is missing, or package.json has no matching line, run the install script by hand once:

Terminal window
node node_modules/shane-new-post/bin/postinstall.js
# or
node node_modules/shane-new-doc/bin/postinstall.js

This command doesn’t depend on the package manager — the path is the same under all three, so any of them works. It performs the exact same steps postinstall always performs — nothing different, just triggered manually instead of automatically. If for some reason that file also doesn’t exist (a very unusual install failure), add the line to package.json yourself. Before:

package.json
{
  "name": "my-docs-site",
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.30.0",
    "astro": "^5.0.0"
  }
}

After — one line added inside "scripts", everything else untouched:

package.json
{
  "name": "my-docs-site",
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
+   "new-doc": "node scripts/new-doc.js"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.30.0",
    "astro": "^5.0.0"
  }
}

For shane-new-post, the equivalent line is "new-post": "node scripts/new-post.js" — same idea, different key and path.