@zentered/next-product-docs
v2.2.0
Published
React/Next.js Render Remote Content
Downloads
47
Readme
Next.js Component for Product Docs
This component helps you to render your product documentation (/docs
) on your
product website. Check out these docs to see a full impression what this
component does.
Typically the website and product (docs) are in separate repositories. This library offers three key functions:
staticPaths
returns all available paths for static site generation in next.jspageProps
returns the required content such as sidebar routes, Table of Contents and MarkdownDocumentation
is a JSX function that contains the render function
You can read more about the whys and hows of this component in the Zentered Blog
Prerequisites
The main purpose of this component is to fetch and render Markdown from a
different repo. In this folder you need to create a manifest.json
file which
contains the link structure for the documentation you want to show. This allows
you to control the sidebar levels and titles for links.
Sample:
/docs
/docs/README.md
...
Manifest:
{
"routes": [
{
"heading": true,
"title": "Next Docs Documentation",
"routes": [
{
"title": "Introduction",
"path": "/docs/README.md"
}
]
}
]
}
You can find complete example here or check out the Example Documentation Manifest.
Installation & Usage
In your Next.js website repo, run:
npm install @zentered/next-product-docs
The location of your product docs can be configured through JSX properties. If
you want to access docs
on a private repository, you'll need to provide a
GITHUB_TOKEN
environment variable.
There are two possible ways to retrieve docs:
Documentation in the same repository as the website
In this example,
the documentation content is stored in content/docs/
:
const defaults = {
docsFolder: 'docs',
rootPath: 'content'
}
Documentation in a remote repository
Another example
where documentation content is stored at
@zentered/next-product-docs-example/content/docs/
:
org: 'zentered,
repo: 'next-product-docs-example',
tag: 'main',
docsFolder: 'docs',
rootPath: 'content'
Additional options
skipPathPrefix: false,
Can be used if the docs are not located in the root of the repository.
useMDX: true,
Limit the level of headings for the Table of Contents
tocMaxDepth: 3,
Switch from Markdown to MDX.
trailingSlash: false, // add a trailing slash to all pages
assetsDestination: null, // use a CDN for assets
debug: process.env.DEBUG === true
Full Example "[[...slug.jsx]]
import Head from 'next/head'
import { pageProps, staticPaths } from 'next-product-docs/serialize'
import Documentation from 'next-product-docs'
const docsOptions = {
docsFolder: 'docs',
rootPath: 'content'
}
export default function Docs({ title, source }) {
return (
<main>
<Documentation source={source} />
</main>
)
}
export async function getStaticPaths() {
const paths = await staticPaths(docsOptions)
return { paths, fallback: false }
}
export async function getStaticProps(ctx) {
const props = await pageProps(ctx, docsOptions)
return { props }
}
Run Locally
Setup
# build dist folder
npm build
# create system-wide link to project folder
npm link
# in the website/next project folder
npm link @zentered/next-product-docs ../next-product-docs
# for continous monitoring in next-product-docs
npm run watch
Additional Components
For convenience we're providing two additional components that help you get started with a sidebar and table of contents. They contain styling classes, so you should customize them as you
You can modify the page [[slug]].jsx
and pass on sidebarRoutes
and
tocHeadings
, which contain the (nested) routes for the sidebar and toc. We're
using react-scroll
to highlight the current section of the page in the table
of contents. In the sidebar you can easily integrate search for example with
Algolia React InstantSearch.
Code Import
You can import code from external files:
This only works when working with a local folder, not by fetching the docs from a remote repository. Check out remark-code-import for further information.
Contributing
Considering contributing to next-product-docs? We'd love to work with you!
To start a local development environment, have a look at our example repo on how to link/unlink the component in a Next.js project.
You can also ping us on Twitter @zenteredco. The only workaround we have at the moment is forking the repository, publish new package versions to GitHub and install them in the Next.js project where we use the component.
Please adhere to the code of conduct.
Acknowledgements & Thanks
- Next.js which showed us the approach of fetching and rendering docs from a remote repo (https://nextjs.org/docs and https://github.com/vercel/next.js/tree/canary/docs)
- next-mdx-remote which allows us to load mdx/md content from anywhere