diff --git a/.gitignore b/.gitignore index 57cb0ba..4c3d36e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ # Dependencies /node_modules +packages/*/node_modules +packages/*/package-lock.json # Production /build diff --git a/docs/devdocify/how-to/add-docset.md b/docs/devdocify/how-to/add-docset.md index d420e36..cbb4491 100644 --- a/docs/devdocify/how-to/add-docset.md +++ b/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. diff --git a/docs/devdocify/how-to/add-playground.md b/docs/devdocify/how-to/add-playground.md index 2fb4d27..4eb183a 100644 --- a/docs/devdocify/how-to/add-playground.md +++ b/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. diff --git a/docs/devdocify/reference/cli.md b/docs/devdocify/reference/cli.md index 0c16b92..a7c0145 100644 --- a/docs/devdocify/reference/cli.md +++ b/docs/devdocify/reference/cli.md @@ -86,6 +86,7 @@ Scaffolds a new DevDocify project in ``. Creates the directory and wr - `package.json` - `docusaurus.config.ts` +- `sidebars.ts` - `docs/index.md` - `src/css/custom.css` - `.gitignore` diff --git a/docs/devdocify/tutorials/quick-start.md b/docs/devdocify/tutorials/quick-start.md index f6ffa45..a49da09 100644 --- a/docs/devdocify/tutorials/quick-start.md +++ b/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. diff --git a/packages/cli/bin/docify.js b/packages/cli/bin/docify.js old mode 100644 new mode 100755 diff --git a/packages/cli/src/commands/new.js b/packages/cli/src/commands/new.js index 229e830..db9878a 100644 --- a/packages/cli/src/commands/new.js +++ b/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); diff --git a/packages/cli/src/utils/assert-project.js b/packages/cli/src/utils/assert-project.js index a3b545a..9585a82 100644 --- a/packages/cli/src/utils/assert-project.js +++ b/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); + } } diff --git a/packages/my-docs/.gitignore b/packages/my-docs/.gitignore new file mode 100644 index 0000000..0b3ceca --- /dev/null +++ b/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 diff --git a/packages/my-docs/docs/index.md b/packages/my-docs/docs/index.md new file mode 100644 index 0000000..e463458 --- /dev/null +++ b/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 +``` diff --git a/packages/my-docs/docusaurus.config.ts b/packages/my-docs/docusaurus.config.ts new file mode 100644 index 0000000..8afcc46 --- /dev/null +++ b/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; diff --git a/packages/my-docs/package.json b/packages/my-docs/package.json new file mode 100644 index 0000000..a39971e --- /dev/null +++ b/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" + } +} \ No newline at end of file diff --git a/packages/my-docs/sidebars.ts b/packages/my-docs/sidebars.ts new file mode 100644 index 0000000..39c61cd --- /dev/null +++ b/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; diff --git a/packages/my-docs/src/css/custom.css b/packages/my-docs/src/css/custom.css new file mode 100644 index 0000000..95dc3ba --- /dev/null +++ b/packages/my-docs/src/css/custom.css @@ -0,0 +1,4 @@ +/** + * Custom CSS for this DevDocify project. + * Add your overrides here. + */