Fix/docs tutorial walkthrough

.gitignore

@@ -1,5 +1,7 @@
 # Dependencies
 /node_modules
+packages/*/node_modules
+packages/*/package-lock.json
 
 # Production
 /build

docs/devdocify/how-to/add-docset.md

@@ -103,6 +103,13 @@ docify validate
 docify build
 ```
 
+Without the CLI, use `npm run` directly:
+
+```bash
+npm run lint-content
+npm run build
+```
+
 ## 8. Verify in the browser
 
 Run the dev server and verify the new docset route and sidebar:
@@ -111,4 +118,10 @@ Run the dev server and verify the new docset route and sidebar:
 docify dev
 ```
 
+Or without the CLI:
+
+```bash
+npm start
+```
+
 Open `http://localhost:3000/myproduct/getting-started` and confirm the sidebar loads your `navigation.json` entries.

docs/devdocify/how-to/add-playground.md

@@ -87,10 +87,10 @@ Run:
 docify build
 ```
 
-If you only want to check link integrity:
+Without the CLI, use `npm run` directly:
 
 ```bash
-docify broken-links
+npm run build
 ```
 
 ## 7. Verify behavior
@@ -101,4 +101,10 @@ Start local dev and test at least one request in the playground UI:
 docify dev
 ```
 
+Or without the CLI:
+
+```bash
+npm start
+```
+
 Confirm the route loads and the sample requests return expected responses.

docs/devdocify/reference/cli.md

@@ -86,6 +86,7 @@ Scaffolds a new DevDocify project in `<directory>`. Creates the directory and wr
 
 - `package.json`
 - `docusaurus.config.ts`
+- `sidebars.ts`
 - `docs/index.md`
 - `src/css/custom.css`
 - `.gitignore`

docs/devdocify/tutorials/quick-start.md

@@ -23,13 +23,13 @@ A new documentation site running locally, with content validation and broken-lin
 
 ## Step 1: Install the CLI
 
-Install the Docify CLI globally:
+From the root of the `doc-platform` repository, link the CLI globally:
 
 ```bash
-npm install -g @devdocify/cli
+cd packages/cli && npm install && npm link
 ```
 
-Confirm it's available:
+Confirm it is available:
 
 ```bash
 docify --version
@@ -39,9 +39,10 @@ docify --version
 
 ## Step 2: Create a project
 
-Scaffold a new DevDocify project in a directory called `my-docs`:
+Navigate to the directory where you want your project, then scaffold it:
 
 ```bash
+cd ~
 docify new my-docs
 ```
 
@@ -60,6 +61,8 @@ npm install
 docify dev
 ```
 
+Or without the CLI: `npm start`.
+
 Open [http://localhost:3000](http://localhost:3000) in your browser. You should see your new docs site.
 
 Edit `docs/index.md` and save. The browser should reload automatically.
@@ -76,11 +79,9 @@ Run the content linter to catch common issues before you build:
 docify validate
 ```
 
-If your `package.json` doesn't have a `lint-content` script yet, add one:
+Or without the CLI: `npm run lint-content`.
 
-```json
-"lint-content": "echo \"No linter configured\""
-```
+The scaffolded project includes a placeholder `lint-content` script. Replace it with a real linter when you are ready.
 
 ---
 
@@ -92,7 +93,7 @@ Build the site and check every internal link:
 docify broken-links
 ```
 
-Fix any broken links reported before continuing.
+Without the CLI, `npm run build` catches broken links because the scaffolded config sets `onBrokenLinks: 'throw'`. Fix any broken links reported before continuing.
 
 ---
 
@@ -104,6 +105,8 @@ Build a production bundle:
 docify build
 ```
 
+Or without the CLI: `npm run build`.
+
 Deploy to Vercel:
 
 1. Push your project to a GitHub repository.

packages/cli/src/commands/new.js

@@ -68,7 +68,12 @@ const config: Config = {
   baseUrl: '/',
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+
+  markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
+  },
 
   i18n: {
     defaultLocale: 'en',
@@ -81,7 +86,7 @@ const config: Config = {
       {
         docs: {
           sidebarPath: './sidebars.ts',
-          routeBasePath: 'docs',
+          routeBasePath: '/',
         },
         blog: false,
         theme: {
@@ -96,8 +101,8 @@ const config: Config = {
       title: '${name}',
       items: [
         {
-          type: 'docSidebar',
-          sidebarId: 'docs',
+          type: 'doc',
+          docId: 'index',
           position: 'left',
           label: 'Docs',
         },
@@ -134,6 +139,15 @@ docify dev
 \`\`\`
 `;
 
+const SIDEBARS = `import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  docs: [{ type: 'autogenerated', dirName: '.' }],
+};
+
+export default sidebars;
+`;
+
 const CUSTOM_CSS = `/**
  * Custom CSS for this DevDocify project.
  * Add your overrides here.
@@ -159,6 +173,7 @@ export async function newCommand(directory) {
     writeFileSync(join(target, 'package.json'), PACKAGE_JSON(name));
     writeFileSync(join(target, 'docusaurus.config.ts'), DOCUSAURUS_CONFIG(name));
     writeFileSync(join(target, 'docs', 'index.md'), DOCS_INDEX(name));
+    writeFileSync(join(target, 'sidebars.ts'), SIDEBARS);
     writeFileSync(join(target, 'src', 'css', 'custom.css'), CUSTOM_CSS);
     writeFileSync(join(target, '.gitignore'), GITIGNORE);
 

packages/cli/src/utils/assert-project.js

@@ -24,4 +24,11 @@ export function assertProject() {
     );
     process.exit(1);
   }
+
+  if (!existsSync(join(cwd, 'node_modules'))) {
+    console.error(
+      chalk.red('✖ node_modules not found. Run ' + chalk.bold('npm install') + ' first.')
+    );
+    process.exit(1);
+  }
 }

packages/my-docs/.gitignore

@@ -0,0 +1,21 @@
+# Dependencies
+node_modules/
+
+# Docusaurus build outputs
+.docusaurus/
+build/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo

packages/my-docs/docs/index.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 1
+slug: /
+title: Welcome
+---
+
+# Welcome to my-docs
+
+This documentation was scaffolded by the DevDocify CLI.
+
+## Getting started
+
+Edit this file at `docs/index.md` to start writing your documentation.
+
+Run your local dev server:
+
+```bash
+docify dev
+```

packages/my-docs/docusaurus.config.ts

@@ -0,0 +1,61 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'my-docs',
+  tagline: 'Documentation powered by DevDocify',
+  favicon: 'img/favicon.ico',
+
+  url: 'https://your-domain.example.com',
+  baseUrl: '/',
+
+  onBrokenLinks: 'throw',
+
+  markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
+  },
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          routeBasePath: '/',
+        },
+        blog: false,
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    navbar: {
+      title: 'my-docs',
+      items: [
+        {
+          type: 'doc',
+          docId: 'index',
+          position: 'left',
+          label: 'Docs',
+        },
+      ],
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

packages/my-docs/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "my-docs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "serve": "docusaurus serve",
+    "lint-content": "echo \"No linter configured yet\""
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.5.2",
+    "@docusaurus/preset-classic": "^3.5.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "^3.5.2",
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=20.17.0"
+  }
+}

packages/my-docs/sidebars.ts

@@ -0,0 +1,7 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  docs: [{ type: 'autogenerated', dirName: '.' }],
+};
+
+export default sidebars;

packages/my-docs/src/css/custom.css

@@ -0,0 +1,4 @@
+/**
+ * Custom CSS for this DevDocify project.
+ * Add your overrides here.
+ */