npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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:

  1. staticPaths returns all available paths for static site generation in next.js
  2. pageProps returns the required content such as sidebar routes, Table of Contents and Markdown
  3. Documentation 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