From 0b3f1c2bd60a9b908725ecd3cc9e24ab1e0fc288 Mon Sep 17 00:00:00 2001 From: Antoine BERNIER Date: Sat, 17 Aug 2024 13:51:35 +0200 Subject: [PATCH] chore: splitting doc --- docs/getting-started/authoring.mdx | 32 +++++ docs/getting-started/docker.mdx | 55 +++++++++ docs/getting-started/github-actions.mdx | 20 ++++ docs/{ => getting-started}/introduction.mdx | 122 +++----------------- src/app/page.tsx | 2 +- 5 files changed, 123 insertions(+), 108 deletions(-) create mode 100644 docs/getting-started/authoring.mdx create mode 100644 docs/getting-started/docker.mdx create mode 100644 docs/getting-started/github-actions.mdx rename docs/{ => getting-started}/introduction.mdx (71%) diff --git a/docs/getting-started/authoring.mdx b/docs/getting-started/authoring.mdx new file mode 100644 index 00000000..62bc4854 --- /dev/null +++ b/docs/getting-started/authoring.mdx @@ -0,0 +1,32 @@ +--- +title: Authoring +description: How to write documentation +nav: 1 +--- + +In your `MDX` folder, create any `path/to/my-document.mdx`: + +```md +--- +title: My Document +description: Lorem ipsum... +nav: 0 +image: dog.png +--- + +MARKDOWN +``` + +### Frontmatter + +Any key is optional. + +- `title`: if not provided, last part of the path is used: `my document` +- `image`: + - relative (to the md file) or absolute path, eg: `dog.png`, `./dog.png`, `../../dog.png`, `/dog.png` or `https://animals.com/dog.png` + - will be used as metadata image if provided +- `nav`: order in the navigation (on the same level) + +### MARKDOWN + +TODO diff --git a/docs/getting-started/docker.mdx b/docs/getting-started/docker.mdx new file mode 100644 index 00000000..86929d3a --- /dev/null +++ b/docs/getting-started/docker.mdx @@ -0,0 +1,55 @@ +--- +title: Docker +description: Docker image generator +nav: 2 +--- + +```sh +$ docker build -t pmndrs-docs . +``` + +```sh +$ cd ~/code/pmndrs/react-three-fiber +$ ( + trap 'kill -9 0' SIGINT + + export _PORT=60141 + + export MDX=./docs + export NEXT_PUBLIC_LIBNAME="React Three Fiber" + export NEXT_PUBLIC_LIBNAME_SHORT="r3f" + export BASE_PATH= + export OUTPUT=export + export HOME_REDIRECT=/getting-started/introduction + export MDX_BASEURL=http://localhost:$_PORT + export EDIT_BASEURL= + export NEXT_PUBLIC_URL= + export ICON=🇨🇭 + export LOGO=/logo.png + + rm -rf "$MDX/out" + + docker run --rm --init -it \ + -v "$MDX":/app/docs \ + -e MDX \ + -e NEXT_PUBLIC_LIBNAME \ + -e BASE_PATH \ + -e DIST_DIR="$MDX/out$BASE_PATH" \ + -e OUTPUT \ + -e HOME_REDIRECT \ + -e MDX_BASEURL \ + -e EDIT_BASEURL \ + -e NEXT_PUBLIC_URL \ + -e ICON \ + -e LOGO \ + pmndrs-docs npm run build + + kill $(lsof -ti:"$_PORT") + npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & + npx -y serve "$MDX/out" & + + wait +) +``` + +Then go to: http://localhost:3000 diff --git a/docs/getting-started/github-actions.mdx b/docs/getting-started/github-actions.mdx new file mode 100644 index 00000000..8dde443f --- /dev/null +++ b/docs/getting-started/github-actions.mdx @@ -0,0 +1,20 @@ +--- +title: Reusable GitHub Actions workflow +description: Call from your CI +nav: 3 +--- + +`pmndrs/docs` provides a [`build.yml`](.github/workflows/build.yml) reusable workflow, any project can use: + +```yml +uses: pmndrs/docs/.github/workflows/build.yml@main + with: + mdx: './docs' + libname: 'React Three Fiber' + libname_short: 'r3f' + home_redirect: '/getting-started/introduction' + icon: '🇨🇭' + logo: '/logo.png' +``` + +See [`pmndrs/react-three-fiber/.github/workflows/docs.yml`](https://github.com/pmndrs/react-three-fiber/blob/master/.github/workflows/docs.yml) for an example implementation. diff --git a/docs/introduction.mdx b/docs/getting-started/introduction.mdx similarity index 71% rename from docs/introduction.mdx rename to docs/getting-started/introduction.mdx index 551db14e..c6dd80e3 100644 --- a/docs/introduction.mdx +++ b/docs/getting-started/introduction.mdx @@ -1,11 +1,20 @@ --- -title: Poimandres documentation -description: A documentation generator for `pmndrs/*` projects. +title: Introduction +description: Documentation generator for `pmndrs/*` projects. +nav: 0 --- ![](gutenberg.jpg) -# Configuration +## INSTALL + +```sh +$ git clone https://github.com/pmndrs/docs.git +$ cd docs +$ npm ci +``` + +## Configuration | var | description | example | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | @@ -46,7 +55,7 @@ becomes (for a `MDX_BASEURL=http://localhost:60141` value): -# dev +## dev ```sh $ ( @@ -54,7 +63,6 @@ $ ( export _PORT=60141 - # [Config](https://github.com/pmndrs/docs#configuration) export MDX=docs export NEXT_PUBLIC_LIBNAME="Poimandres" export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs" @@ -81,7 +89,7 @@ Then go to: http://localhost:3000 > [!TIP] > If `HOME_REDIRECT=` empty, `/` will not redirect, and instead displays an index of libraries. -# build +## build ```sh $ ( @@ -91,14 +99,13 @@ $ ( export _PORT=60141 - # [Config](https://github.com/pmndrs/docs#configuration) export MDX=docs export NEXT_PUBLIC_LIBNAME="Poimandres" export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs" export BASE_PATH= export DIST_DIR= export OUTPUT=export - export HOME_REDIRECT=/introduction + export HOME_REDIRECT=/getting-started/introduction export MDX_BASEURL=http://localhost:$_PORT export EDIT_BASEURL= export NEXT_PUBLIC_URL= @@ -116,102 +123,3 @@ $ ( ``` http://localhost:3000 - -# Docker - -```sh -$ docker build -t pmndrs-docs . -``` - -```sh -$ cd ~/code/pmndrs/react-three-fiber -$ ( - trap 'kill -9 0' SIGINT - - export _PORT=60141 - - # [Config](https://github.com/pmndrs/docs#configuration) - export MDX=./docs - export NEXT_PUBLIC_LIBNAME="React Three Fiber" - export NEXT_PUBLIC_LIBNAME_SHORT="r3f" - export BASE_PATH= - export OUTPUT=export - export HOME_REDIRECT=/getting-started/introduction - export MDX_BASEURL=http://localhost:$_PORT - export EDIT_BASEURL= - export NEXT_PUBLIC_URL= - export ICON=🇨🇭 - export LOGO=/logo.png - - rm -rf "$MDX/out" - - docker run --rm --init -it \ - -v "$MDX":/app/docs \ - -e MDX \ - -e NEXT_PUBLIC_LIBNAME \ - -e BASE_PATH \ - -e DIST_DIR="$MDX/out$BASE_PATH" \ - -e OUTPUT \ - -e HOME_REDIRECT \ - -e MDX_BASEURL \ - -e EDIT_BASEURL \ - -e NEXT_PUBLIC_URL \ - -e ICON \ - -e LOGO \ - pmndrs-docs npm run build - - kill $(lsof -ti:"$_PORT") - npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & - npx -y serve "$MDX/out" & - - wait -) -``` - -Then go to: http://localhost:3000 - -# Reusable GitHub Actions workflow - -`pmndrs/docs` provides a [`build.yml`](.github/workflows/build.yml) reusable workflow, any project can use: - -```yml -uses: pmndrs/docs/.github/workflows/build.yml@main - with: - mdx: './docs' - libname: 'React Three Fiber' - libname_short: 'r3f' - home_redirect: '/getting-started/introduction' - icon: '🇨🇭' - logo: '/logo.png' -``` - -See [`pmndrs/react-three-fiber/.github/workflows/docs.yml`](https://github.com/pmndrs/react-three-fiber/blob/master/.github/workflows/docs.yml) for an example implementation. - -# Authoring - -In your `MDX` folder, create any `path/to/my-document.mdx`: - -```md ---- -title: My Document -description: Lorem ipsum... -image: dog.png -nav: 0 ---- - -MARKDOWN -``` - -## Frontmatter - -Any key is optional. - -- `title`: if not provided, last part of the path is used: `my document` -- `image`: - - relative (to the md file) or absolute path, eg: `dog.png`, `./dog.png`, `../../dog.png`, `/dog.png` or `https://animals.com/dog.png` - - will be used as metadata image if provided -- `nav`: order in the navigation (on the same level) - -## MARKDOWN - -TODO diff --git a/src/app/page.tsx b/src/app/page.tsx index 83b1e646..45339b28 100644 --- a/src/app/page.tsx +++ b/src/app/page.tsx @@ -112,7 +112,7 @@ const libs: Record = { }, docs: { title: 'Docs', - url: '/introduction', + url: '/getting-started/introduction', github: 'https://github.com/pmndrs/docs', description: 'Documentation generator for `pmndrs/*`', image: docsShare.src,