@exor404/mdslides 0.1.2 → 0.1.3

package/README.md

@@ -12,32 +12,78 @@ dev server or builds a self-contained `dist/` you can host anywhere static.
 ## Quick start
 
 ```bash
-mdslides ./chemistry          # scaffolds a project, then presents it
+npx @exor404/mdslides@latest
 ```
 
-Point `mdslides` at a folder and it scaffolds a project: it **asks for a
-name**, writes `<name>.md` (e.g. `chemistry.md`) with three sample slides — a
-title page, a list, and a help slide — plus a `mdslides.config.js`, then opens
-the dev server. The name defaults to the folder, so pressing Enter at
-`Name your presentation (chemistry):` gives you `chemistry/chemistry.md`. That
-file *is* your deck — edit it and the slides live-reload.
+No install step. It **asks for a name**, scaffolds `<name>/<name>.md` (three
+sample slides — a title page, a list, and a help slide) plus a
+`mdslides.config.js`, and opens the dev server. The name defaults to the current
+folder, so pressing Enter at `Name your presentation (chemistry):` gives you
+`chemistry/chemistry.md`. That file *is* your deck — edit it and the slides
+live-reload.
+
+Point it at a folder for the other commands:
 
 ```bash
-mdslides ./chemistry          # present (dev server, live-reload)
-mdslides build ./chemistry    # static build → ./chemistry/dist/
-mdslides preview ./chemistry  # serve the built dist/
-mdslides export ./chemistry   # → chemistry.pdf (one page per slide)
+npx @exor404/mdslides ./chemistry          # present (dev server, live-reload)
+npx @exor404/mdslides build ./chemistry    # static build → ./chemistry/dist/
+npx @exor404/mdslides preview ./chemistry  # serve the built dist/
+npx @exor404/mdslides export ./chemistry   # → chemistry.pdf (one page per slide)
 ```
 
-Already have a deck? Point straight at the file: `mdslides ./chemistry.md`.
+Already have a deck? Point straight at the file: `npx @exor404/mdslides ./chemistry.md`.
+
+> **Heads-up:** `npm install @exor404/mdslides` only *installs* the package —
+> running the CLI (via `npx`, as above) is what scaffolds and presents. Using
+> `npx` also keeps the engine's dependencies in npx's cache instead of bloating
+> a project's `node_modules`.
+
+Prefer a global command? `npm i -g @exor404/mdslides` makes `mdslides` available
+directly (`mdslides ./chemistry`).
 
-Try the bundled example:
+Try the bundled example from a clone:
 
 ```bash
 npm install
 npm run dev        # opens ./example
 ```
 
+## Install
+
+The package is published on the public npm registry as
+[`@exor404/mdslides`](https://www.npmjs.com/package/@exor404/mdslides). Pick the
+option that suits you:
+
+**No install (recommended).** `npx` fetches and caches the latest version, then
+runs it — nothing is added to your project:
+
+```bash
+npx @exor404/mdslides@latest          # prompts for a name, scaffolds + presents
+```
+
+**Global install.** Puts an `mdslides` command on your `PATH`:
+
+```bash
+npm install -g @exor404/mdslides
+mdslides ./chemistry                  # then use it anywhere
+mdslides --help                       # (or run with no folder to start fresh)
+```
+
+Update later with `npm update -g @exor404/mdslides`; remove with
+`npm uninstall -g @exor404/mdslides`.
+
+**As a project dependency.** Add it to a repo so collaborators get the same
+version via `npm install`:
+
+```bash
+npm install -D @exor404/mdslides
+npx mdslides ./chemistry              # resolves from local node_modules
+```
+
+> Requires **Node 18+**. Installing the package pulls in its rendering engine
+> (Astro, Shiki, KaTeX) — that's why `npx` is the lightest way to try it: those
+> dependencies stay in npx's cache instead of your project's `node_modules`.
+
 ## The deck model
 
 **One markdown file is the whole deck.** Every `#` (H1) heading starts a new
@@ -154,10 +200,10 @@ automation token stored as the `NPM_TOKEN` repository secret.
 ### How the pipeline works
 
 ```
-push tag v0.1.2 ──► GitHub Actions ──► checkout ──► setup Node 22
+push tag v0.1.3 ──► GitHub Actions ──► checkout ──► setup Node 22
                                           │
-                                          ├─ guard: tag (v0.1.2) must equal
-                                          │   package.json "version" (0.1.2),
+                                          ├─ guard: tag (v0.1.3) must equal
+                                          │   package.json "version" (0.1.3),
                                           │   else the run fails
                                           │
                                           └─ npm publish  (auth: NPM_TOKEN)
@@ -190,9 +236,9 @@ on your behalf.
 Once the secret is in place, every release is three commands:
 
 ```bash
-npm version patch          # bumps package.json (0.1.1 → 0.1.2) and commits + tags v0.1.2
+npm version patch          # bumps package.json (0.1.2 → 0.1.3) and commits + tags v0.1.3
 git push origin main       # push the version-bump commit
-git push origin v0.1.2     # push the tag → the pipeline publishes
+git push origin v0.1.3     # push the tag → the pipeline publishes
 ```
 
 `npm version patch` (or `minor` / `major`) bumps `package.json`, makes the commit,
@@ -203,8 +249,8 @@ green the new version is live on npm.
 **Prefer to bump by hand?** Edit `"version"` in `package.json`, then:
 
 ```bash
-git commit -am "🔖 Release 0.1.2"
-git tag v0.1.2             # must match package.json exactly, or the guard fails
+git commit -am "🔖 Release 0.1.3"
+git tag v0.1.3             # must match package.json exactly, or the guard fails
 git push && git push --tags
 ```
 

package/app/integrations/mdslides-assets.js

@@ -23,7 +23,15 @@ const MIME = {
 };
 
 const EXCLUDED_TOP = new Set(['dist', 'node_modules', '.git', '.astro', '.vscode', '.idea']);
-const EXCLUDED_FILES = new Set(['mdslides.config.js']);
+const EXCLUDED_FILES = new Set([
+  'mdslides.config.js',
+  // Project scaffolding that lives alongside the deck (npm create … layout) —
+  // never part of the presentation, so keep it out of the built dist/.
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+]);
 
 function isExcludedRel(rel) {
   if (!rel || rel === '.' || rel === '..') return true;

package/bin/cli.js

@@ -60,7 +60,10 @@ function parseArgs(argv) {
     }
   }
 
-  if (!file) {
+  // No target + the default `dev` command → start a brand-new project: we'll
+  // prompt for a name and scaffold it. Any other command needs an explicit
+  // target (there's nothing to build/preview/export yet).
+  if (!file && cmd !== 'dev') {
     fail('Missing target.\nUsage: mdslides [dev|build|preview|export] [--theme <name>] <folder|file.md>');
   }
 
@@ -130,6 +133,21 @@ async function scaffoldProject(dir) {
   return scaffoldDeck(resolve(dir, `${stem}.md`));
 }
 
+// Start a project from scratch when `mdslides` is run with no target (e.g.
+// `npx @exor404/mdslides`): ask for a name, then create `<name>/<name>.md` in
+// the current directory and present it. No install or extra command needed.
+async function scaffoldNewProject() {
+  const fallback = slugify(basename(process.cwd())) || 'presentation';
+  const answer = await ask(`Name your presentation (${fallback}): `, fallback);
+  const stem = slugify(answer.replace(/\.md$/i, '')) || fallback;
+  const dir = resolve(process.cwd(), stem);
+  if (existsSync(dir) && statSync(dir).isDirectory() && findDeckInDir(dir)) {
+    // A deck already lives here — open it instead of clobbering anything.
+    return findDeckInDir(dir);
+  }
+  return scaffoldDeck(resolve(dir, `${stem}.md`));
+}
+
 function scaffoldDeck(deckPath) {
   const templatePath = resolve(__dirname, 'templates', 'slides.md');
   try {
@@ -169,7 +187,7 @@ async function loadUserConfig(source) {
 }
 
 const { cmd, theme: cliTheme, file } = parseArgs(process.argv);
-const deckFile = await resolveDeck(file);
+const deckFile = file ? await resolveDeck(file) : await scaffoldNewProject();
 const source = dirname(deckFile);
 
 ensureDefaultConfig(source);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exor404/mdslides",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Markdown in, presentation out.",
   "type": "module",
   "bin": {