From a8de5b63eb00154971120d4e096919b1089085a1 Mon Sep 17 00:00:00 2001 From: mrjvs Date: Fri, 26 Apr 2024 22:01:37 +0200 Subject: [PATCH] Release create-guider --- README.md | 2 +- apps/create-guider/package.json | 2 +- .../templates/main/next.config.mjs | 9 + .../guides/getting-started/installation.mdx | 236 ++++++++++-------- 4 files changed, 145 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index a7299557..252d99e0 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ - no abstraction, you're using well-known libraries, almost no need for neato-specific google searches ## Packages +- @neato/guider - beautiful documentation generator framework based on nextjs - @neato/config - load configurations from various sources with type-safety and validation (BETA) -- @neato/guider - beautiful documentation generator framework based on nextjs (ALPHA) ## Upcoming packages - @neato/router - http router based on fastify diff --git a/apps/create-guider/package.json b/apps/create-guider/package.json index 7132e6a2..ed1a1aca 100644 --- a/apps/create-guider/package.json +++ b/apps/create-guider/package.json @@ -1,6 +1,6 @@ { "name": "@neato/create-guider", - "version": "0.0.2", + "version": "1.0.0", "description": "Beautiful documentation sites, without all the hassle", "main": "./entry.js", "type": "module", diff --git a/apps/create-guider/templates/main/next.config.mjs b/apps/create-guider/templates/main/next.config.mjs index e69de29b..f588b028 100644 --- a/apps/create-guider/templates/main/next.config.mjs +++ b/apps/create-guider/templates/main/next.config.mjs @@ -0,0 +1,9 @@ +import { guider } from '@neato/guider'; + +const withGuider = guider({ + themeConfig: './theme.config.tsx', +}); + +export default withGuider({ + output: 'export', +}); diff --git a/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx b/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx index 64c4cc09..a37abddd 100644 --- a/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx +++ b/apps/docs/pages/docs/guider/guides/getting-started/installation.mdx @@ -10,110 +10,142 @@ Get started with `@neato/guider` project in under 5 minutes. Follow the steps below to make a new Guider project. - - - ### Create a Next.JS project and install Guider - To install a Next.JS project with guider, install the following dependencies: - ```sh npm2yarn - npm install next@latest react@latest react-dom@latest @neato/guider@latest - ``` - then add the following scripts to your `package.json`: - ```json title="package.json" showLineNumbers - { - "scripts": { - "dev": "next dev", - "build": "next build", - "start": "next start", - "lint": "next lint" - } - } - ``` - - - ### Add a Next.JS config - Create or replace the following `next.config.mjs` file in your project's root directory. - ```js title="next.config.mjs" showLineNumbers - import { guider } from "@neato/guider"; - - const withGuider = guider({ - // The location of your theme file, created in the next step - themeConfig: './theme.config.tsx', - }); - - export default withGuider({ - // These are the normal Next.JS settings. - // Check out Next.JS docs: https://nextjs.org/docs/app/api-reference/next-config-js - output: 'export', - }); - ``` - - - ### Create a theme config - Next, create a `theme.config.tsx`. This will be the home for all of your configuration and customization of Guider: - ```ts title="theme.config.tsx" showLineNumbers - import { defineTheme, directory, link } from '@neato/guider/theme'; - - export default defineTheme({ - directories: [ - directory("main", { // ID of your directory (unique per site), used for referencing in your page files - sidebar: [ - // Creates a link in your sidebar, add more below it - link("Home", "/") - ] - }) - ], - }); - ``` - - - ### Create entrypoint files - Finally, create two files `pages/_app.tsx` and `pages/404.tsx`. They should be in your pages directory. - The app file is to setup the layout system and styled for Guider. The 404 file holds a preset "page not found" view, feel free to customize it. - - - ```tsx - import '@neato/guider/style.css'; - import { createGuiderApp } from '@neato/guider/client'; - - export default createGuiderApp(); + + + + + + ### Run the automatic installer + Start the installer by running this command: + ```sh + npx @neato/create-guider ``` - - - ```tsx - import { createNotFoundPage } from '@neato/guider/client'; - - export default createNotFoundPage(); + + + ### Install dependencies + Navigate to the directory the installer made and run the following: + ```sh npm2yarn + npm install + ``` + + + ### Ready to write! + Your project has been fully setup, all that's left is to fill it with content. + + Run the developer server with `npm run dev{:sh}` and see the first page by visiting the link shown in the console. + + The Next.JS development server is infamous for being slow. The final build of the site will be **much** faster. + + + + + + + + ### Create a Next.JS project and install Guider + To install a Next.JS project with guider, install the following dependencies: + ```sh npm2yarn + npm install next@latest react@latest react-dom@latest @neato/guider@latest + ``` + then add the following scripts to your `package.json`: + ```json title="package.json" showLineNumbers + { + "scripts": { + "dev": "next dev", + "build": "next build", + "start": "next start", + "lint": "next lint" + } + } + ``` + + + ### Add a Next.JS config + Create or replace the following `next.config.mjs` file in your project's root directory. + ```js title="next.config.mjs" showLineNumbers + import { guider } from "@neato/guider"; + + const withGuider = guider({ + // The location of your theme file, created in the next step + themeConfig: './theme.config.tsx', + }); + + export default withGuider({ + // These are the normal Next.JS settings. + // Check out Next.JS docs: https://nextjs.org/docs/app/api-reference/next-config-js + output: 'export', + }); + ``` + + + ### Create a theme config + Next, create a `theme.config.tsx`. This will be the home for all of your configuration and customization of Guider: + ```ts title="theme.config.tsx" showLineNumbers + import { defineTheme, directory, link } from '@neato/guider/theme'; + + export default defineTheme({ + directories: [ + directory("main", { // ID of your directory (unique per site), used for referencing in your page files + sidebar: [ + // Creates a link in your sidebar, add more below it + link("Home", "/") + ] + }) + ], + }); + ``` + + + ### Create entrypoint files + Finally, create two files `pages/_app.tsx` and `pages/404.tsx`. They should be in your pages directory. + The app file is to setup the layout system and styled for Guider. The 404 file holds a preset "page not found" view, feel free to customize it. + + + ```tsx + import '@neato/guider/style.css'; + import { createGuiderApp } from '@neato/guider/client'; + + export default createGuiderApp(); + ``` + + + ```tsx + import { createNotFoundPage } from '@neato/guider/client'; + + export default createNotFoundPage(); + ``` + + + + + ### Setup typescript + To make Guider work, you will need to slightly modify your tsconfig.json. If you don't have a tsconfig.json file yet, just make one at the root of your project. + + If you do already have typescript, you can just change the single option in your existing config. + + ```json title="tsconfig.json" + { + "compilerOptions": { + "moduleResolution": "Bundler", // [!code focus] + } + } + ``` + + + ### Ready to write documentation! + Your project has been fully setup, all that's left is to fill it with content. Try it out by making a file in your pages directory: + ```md title="pages/index.mdx" + # Hello world + This is my first `@neato/guider` page! ``` - - - - - ### Setup typescript - To make Guider work, you will need to slightly modify your tsconfig.json. If you don't have a tsconfig.json file yet, just make one at the root of your project. - - If you do already have typescript, you can just change the single option in your existing config. - - ```json title="tsconfig.json" - { - "compilerOptions": { - "moduleResolution": "Bundler", // [!code focus] - } - } - ``` - - - ### Ready to write documentation! - Your project has been fully setup, all that's left is to fill it with content. Try it out by making a file in your pages directory: - ```md title="pages/index.mdx" - # Hello world - This is my first `@neato/guider` page! - ``` - And run with `npm run dev{:sh}` and see your first page by visiting the link shown in the console. - - The Next.JS development server is infamous for being slow. The final build of the site will be **much** faster. - - - + And run with `npm run dev{:sh}` and see your first page by visiting the link shown in the console. + + The Next.JS development server is infamous for being slow. The final build of the site will be **much** faster. + + + + + ## What's next?