Low level documentation websites using Next.js
To initialize a guild-docs package, you can use npx:
npx @pablosz/guild-docs init
$ npx @pablosz/guild-docs init
Configuration files added!
Dependencies added!
Now you can install dependencies: "pnpm i", "yarn" or "npm i"; and then run the ___"dev"___ script, either "pnpm dev", "yarn dev" or "npm run dev"
🎉 Now you can install dependencies and run the "dev" script, and you are set to go!
By default the "init" command creates a "docs" folder, where you can use MDX and create any file or folder structure.
The MDX implementation we use has a single inconvenience/tradeoff, which is that it's NOT possible to use imports inside the MDX files. Here you can read a short description of the reason why this happens.
But you can define Custom Components to be used inside the MDX in the app.tsx file, using the included helper "ExtendComponents" function:
Already added in the default
_app.tsx
file
You can also use
next/dynamic
to lazy load components:import dynamic from 'next/dynamic';
const SomeHeavyComponent = dynamic(() => import('./SomeHeavyComponent'));
import { ExtendComponents } from '@pablosz/guild-docs-client';
// ...
ExtendComponents({
HelloWorld() {
return <p>Hello World!</p>;
},
});
// ...
And then use them in your files:
# Hello World
<HelloWorld />
By default, in initialization, a routes.ts
file is created as it follows:
IRoutes
is a recursive object type designed to make and customize the routes, with a specialGenerateRoutes
helper function that reads from a folder pattern(s) (using minimatch patterns) with globby.
import { IRoutes, GenerateRoutes } from '@pablosz/guild-docs-server';
export function getRoutes(): IRoutes {
const Routes: IRoutes = {
_: {
index: {
$name: 'Home',
$routes: [['index', 'Home Page']],
},
},
};
GenerateRoutes({
Routes,
folderPattern: 'docs',
basePath: 'docs',
basePathLabel: 'Documentation',
labels: {
index: 'Docs',
},
});
return Routes;
}
In this example, the base routes has a route that goes to the "/" path, with the label "Home Page".
And the GenerateRoutes
function is used to get all the "docs" folder, using a basePath "/docs" with a label "Documentation" in the navigation, and the labels that are useful for setting the expected labels in every step, where you can use the syntax foo.bar.baz
to set the labels in deep paths.
This project is using pnpm workspaces
Make sure to install pnpm: https://pnpm.io/installation
And simply install the dependencies:
pnpm i
- The examples are in examples/*
- The packages are packages/*