remorses / dokz

Effortless documentation with Next.js and MDX

Effortless documentation with Next.js and MDX

Warning: this project is no longer maintained, consider using Nextra or Notaku (suppports docs site grneration from Notion docs).

Sponsor:

Notaku

🔥 Features

• File based routing
• SideBar automatically generated from mdx paths
• Table of contents generated from headings
• Dark Mode
• Preview React Components inside jsx code blocks
• Can be integrated with existing Nextjs app

Quick Start

We recommend creating a new Dokz app using create-dokz-app, which sets up everything automatically for you. To create a project, run:

npm init dokz-app
# or
yarn create dokz-app

After the installation is complete run npm run dev to start the development server. Try editing pages/index.mdx and see the result on your browser.

Manual Setup

warning: you should use npm init dokz-app if you don't have an existing next application

You can also install dokz in an existing nextjs application:

npm install dokz @emotion/react @chakra-ui/react @emotion/styled framer-motion

Add the dokz provider to the main nextjs entrypoint

// _app.jsx
import { DokzProvider } from 'dokz'
import { ChakraProvider } from '@chakra-ui/react'
import React from 'react'

export default function App(props) {
    const { Component, pageProps } = props
    return (
        <ChakraProvider>
            <DokzProvider headerLogo={<img src='/logo.svg' width='100px' />}>
                <Component {...pageProps} />
            </DokzProvider>
        </ChakraProvider>
    )
}

Add withDokz in the next.config.js file

const { withDokz } = require('dokz/dist/plugin')

module.exports = withDokz()

Create a new mdx document inside tha pages folder

# Heading

Ullamco ipsum id irure do occaecat minim. Cupidatat exercitation magna sit sunt aliqua voluptate excepteur amet dolor ea do. Consectetur veniam deserunt ullamco irure ullamco. Voluptate magna tempor elit voluptate velit enim dolor nulla sit fugiat exercitation. Anim deserunt Lorem aliquip cillum duis deserunt consequat sit culpa commodo.

> Node this is important

## Subjeading

Quis anim minim ullamco aliquip excepteur do pariatur eiusmod duis eu non. Duis deserunt Lorem nulla non duis voluptate dolore et. Do veniam mollit in do ad id enim anim dolore sint labore quis consequat.

To start developing your application run npm run dev. This starts the development server on http://localhost:3000.

Visit http://localhost:3000 to view your application.

dokz's Issues

Missing license?

There's currently no license in this repo.

I'd like to understand if this can be safely used for Open Source and commercial projects.

i18n

Is there any support to be able to provide translatable content?

Unhandled runtime error related to sidebar

I wanted to give dokz a try with an existing set of .mdx files I have (a docz project).

I installed dokz in a fresh project using create-dokz-app. I copied all my .mdx files into the pages directory.

The directory tree is very simple:

// in the ./pages directory
index.mdx
rootPageA.mdx
rootPageB.mdx
directoryA // contains multiple .mdx files
directoryB // contains multiple .mdx files

I removed the sidebarOrdering prop from the <DokzProvider> because I just want to use the default navigation.

Unfortunately I am getting an unhandled runtime error that seems to be related to the sidebar navigation:

Unhandled Runtime Error
TypeError: Cannot convert undefined or null to object

Call Stack
Function.keys
<anonymous>
eval
node_modules/dokz/dist/components/SideNav.js (76:0)
eval
node_modules/lodash/_baseOrderBy.js (24:0)
arrayMap
node_modules/lodash/_arrayMap.js (16:0)
eval
node_modules/lodash/_baseOrderBy.js (23:0)
eval
node_modules/lodash/_baseMap.js (17:0)
eval
node_modules/lodash/_createBaseEach.js (24:0)
baseMap
node_modules/lodash/_baseMap.js (16:0)
baseOrderBy
node_modules/lodash/_baseOrderBy.js (22:0)
Object.orderBy [as default]
node_modules/lodash/orderBy.js (44:0)
applySidebarOrdering
node_modules/dokz/dist/components/SideNav.js (75:0)
exports.SideNav
node_modules/dokz/dist/components/SideNav.js (54:0)
renderWithHooks
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (15055:18)
mountIndeterminateComponent
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (17734:13)
beginWork
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (18848:16)
HTMLUnknownElement.callCallback
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (440:14)
Object.invokeGuardedCallbackDev
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (489:16)
invokeGuardedCallback
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (544:31)
beginWork$1
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (23455:7)
performUnitOfWork
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (22406:12)
workLoopSync
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (22382:22)
performSyncWorkOnRoot
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (22008:9)
scheduleUpdateOnFiber
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (21440:7)
updateContainer
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (24625:3)
<unknown>
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (25010:7)
unbatchedUpdates
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (22155:12)
legacyRenderSubtreeIntoContainer
file:///home/my_user/projects/dokz-test/.next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (25009:5)
Object.hydrate
/_next/static/development/dll/dll_f9de5cbc314a1e41f91e.js (25075:10)
renderReactElement
../../client/index.js (397:6)
_callee3$
../../client/index.js (523:2)
tryCatch
node_modules/regenerator-runtime/runtime.js (45:14)
Generator.invoke [as _invoke]
node_modules/regenerator-runtime/runtime.js (274:0)
Generator.prototype.<computed> [as next]
node_modules/regenerator-runtime/runtime.js (97:0)
asyncGeneratorStep
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (3:0)
_next
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (25:0)
eval
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (32:0)
new Promise
<anonymous>
eval
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (21:0)
_doRender
webpack-internal:///./node_modules/next/dist/client/index.js (686:20)
doRender
webpack-internal:///./node_modules/next/dist/client/index.js (636:20)
_callee2$
../../client/index.js (305:10)
tryCatch
node_modules/regenerator-runtime/runtime.js (45:14)
Generator.invoke [as _invoke]
node_modules/regenerator-runtime/runtime.js (274:0)
Generator.prototype.<computed> [as next]
node_modules/regenerator-runtime/runtime.js (97:0)
asyncGeneratorStep
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (3:0)
_next
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (25:0)
eval
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (32:0)
new Promise
<anonymous>
eval
node_modules/next/node_modules/@babel/runtime/helpers/asyncToGenerator.js (21:0)
_render
webpack-internal:///./node_modules/next/dist/client/index.js (475:18)

The error persists event when I pass a custom sidebarOrdering prop.

CSP nonce

Hello, thank you for this great project.

Context:

In Next you can add a nonce to the head component.
<Head nonce={nonce}>

Problem

Once I add the plugin, the nonce is no longer applied. Before starting to dig into this I would like to ask if this is something that is not supported if you use dokz (for one reason or another).

Thank you

Cannot use with NextJS Export

Sidebars fail to properly generate when running next export. Export doesn't run a server, so the sidebar.json is never generated and the sidebar is not rendered in the static output. This means dokz can't be used with a static hosting service like Github Pages.

Collapsible menu in sidebar not respecting the sidebarOrdering

My pages directory structure is represented like the following

+-- areas-of-interest
|   +--coding-conventions
|    | +--global.mdx
|    | +--javascript.mdx
|    | +--ruby.mdx
+-- code-reviews.mdx
+-- quality-assurance.mdx
+-- on-call.mdx

in my _app.tsx file I have the following for the sidebarOrdering

// _app.tsx

const sidebarOrder = {
  'index.md': true,
  'areas-of-interest': {
     'coding-conventions: {
         global: true,
         javascript: true,
         ruby: true,
     },
    'code-reviews': true,
    'quality-assurance' : true,
    'on-call': true,
  }
}

However, coding-conventions, which results in a collapsible menu, is always at the end of the list in the sidebar. I can change the order of the items within the collapsible menu, but I can't get the collapsible menu to show up first in the list.

Is there any way to accomplish this?

Allow option for react component preview to show alongside the code.

Current situation analysis

Right now, the current way to preview react components doesn't offer a good user experience. It's requires a lot more cognitive effort to always keep in mind the state of the output while navigating the code.

Proposed solution

A better solution would be one that allows the code and the output to be visible side by side, at the same time. In my opinion, this would tremendously improve the user experience for users navigating a site using dokz.
This is exactly what code-sandbox and in some way codepen does. Which is really good.

Alternative

I understand a different implementation might be much more complex, in that case, below is an alternative solution to the problem and is good too. This solution shows the code beneath while the output is shown above at the same time. The only issue with this might be instances where the lines of code are quite much and requires the page to be scrolled. down more.

Dokz website

The website documentation is broken https://dokz.vercel.app/docs/getting-started

How to use plugins?

Is there any ways to use plugins and hook into @next/mdx?

I tried this, but that did not work. Is it possible?

The plugins were installed.

Migrate to chakraUI v1

Would be nice for longer term support and to limit breaking changes

getStaticProps and getStaticPaths ?

is there a way to define getStaticProps and getStaticPaths per page?

Error: can't find react/jsx-dev-runtime

./pages/_app.jsx
Module not found: Can't resolve 'react/jsx-dev-runtime' in '/home/sidwebworks/Desktop/Github/codopedia/pages'

I just created a new project using

yarn create dokz-app

tried with npx also same issue

Built in Blog

The first blog implementation is already done, you can read more in the documentation

I still need to add discoverability via a blogRootsPath to find the documents for the list

Then you put an index.tsx page in blog folder and export the BlogList component from Dokz to show the blog posts found in the blogRootPath folder

Generating the static pages - no sidebar

When using next export, it is possible to export the static pages to the "root/out" directory with no issues, however, the sidebar is nowhere to be found.
Is it possible to have Dokz include the sidebar when exporting somehow?

Live code editing is broken due to padding

To reproduce, go do https://dokz.site/docs or create a new doc via npm init dokz-app

Importing partials lead to recursive navigation panes

Hi. I tried setting up Dokz with my nextjs project and it worked well. I was trying to import a partial file from within my MDX file like this:

---
id: typescript
title: TypeScript
---

import Content from '../generated-config/typescript.mdx';

<Content />

and this gave me a recursive frame like this:

Any help appreciated. Thanks.

CC: @remorses

Documentation versioning

It would be great to enable documentation versioning (like in docusaurus for instance).

Allow for custom darkmode switch

I would like to define a custom darkmode switch, so I can control switching to dark mode myself, as I need to show a different logo depending on which mode I am in

Use full space for right sidebar

The right sidebar, which shows all the subheaders, when being used on a 1920x1080p screen is not using all the space it has available, because there is a fixed witdth of 200px defined.

When removing it the size of the box changes per page, which is maybe not desirable.

If you want I can try to make a PR for that

Throws "Invalid Hook Call" on init

when creating a project via npm init dokz-app the follow is generated when spinning up a dev server (npm run dev)

Working in a new directory, with nothing but an npm i command run previously.

Next and Previous document buttons

Index route 404

Current behavior

Clicking on the index.html index.mdx doc goes to /index. This will result in 404 in trailing slash config because it will redirect to /index/, which resolves to /index/index.html.

Expected behavior

Clicking on the index.html index.mdx doc should go to /.

Suggestion to fix

I think this code snippet is supposed to solve the problem: https://github.com/remorses/dokz/blob/master/dokz/src/plugin/getMdxFilesIndex.ts#L44-L47, but it should be

    // replace `index` with empty string
    relativePath.replace(/^index$/, '')

    // remove this line
    // relativePath = relativePath || '/'
    return '/' + relativePath
}

Let me know what you think and I'm happy to send a PR

blockquote with multiple paragraphs displayed in row

I would expect this to display in a column

Props?

Great work!

In Docz, there's a way to see the prop-types a component uses, ie

<Props of={Button} />

Are there plans for this sort of functionality? Then I can move away from Storybook hurrah!

Allow to prefix Nav Items with Icons

I would like to be able to prefix my categories, so like "General" or "Customizing" on the dokz docs with an icon.

Search functionality

Long titles overlap Table of Contents sidebar

Issue

Long titles overlap the Table of Contents sidebar on the right side.

Solution

Add a Table of Contents width/height prop or adjust width/height according to text instead of just overflowing. This project doesn't seem to be maintained anymore but it's worth a try.

Dokz 1.0.30 breaks Landing Blocks on Safari

I have a website that combine Landing Blocks and Dokz in a single nextjs intance.

With Dokz 1.0.29 the statically extracted landing page looks like this in Safari:

https://5ee22377d3f54bed49b934e2--labs-sterblue-com.netlify.app

Then without changing anyting else, moving Dokz to 1.0.30, the landing page looks like this:

https://5eea4dd7445a8b01dd86992d--labs-sterblue-com.netlify.app

I suspect this might be linked to a version change of layout-kit-react maybe?

Deployment to any subdirectories (e.g. by adding hash routing)

Hi @remorses, I'm really glad to discover dokz, great work! 🙌

My teammates and I have been using docz for a while and unfortunately we’re stuck with version 0.13.x, because docz v1 and v2 do not support hash routing: doczjs/docz#763

Because of that, we cannot deploy our docs to a subdirectory, because the build artifact wrongly expect that our index.html will be at example.com and not at example.com/whatever/.

The solution is blocked by gatsbyjs/gatsby#14161.

As of today doczjs/docz#763 is the number one docz bug by the number of 👍. Wondering if we could solve that problem with Next under the hood anyhow, which can give dokz an initial flow of users?

WDYT?

Defer external and internal links

At the moment links on a page that link to another page on the website are treated as external and result in reloading the page, which defeats the purpose of Next.js universal routing.

Would be cool to separate links and the ones that internal (start with a slash) should be wrapped in a <Link>

Scroll back to Top

When clicking a link inside the docs (for example the bottom navigation) it doesnt scroll to the top on the next page.

This is not a good behaviour IMO.

Impossible to install Dokz

Hello,
When I install Dokz with the command npm init dokz-app and npm install, I have this error :

> next dev

ready - started server on http://localhost:3000
[ info ]  generating mdx sidebar file
info  - automatically enabled Fast Refresh for 1 custom loader
error - ./node_modules/@chakra-ui/portal/dist/esm/portal.js
Attempted import error: 'useCallbackRef' is not exported from '@chakra-ui/hooks'.
wait  - compiling...
error - ./node_modules/@chakra-ui/portal/dist/esm/portal.js
Attempted import error: 'useCallbackRef' is not exported from '@chakra-ui/hooks'.
event - build page: /next/dist/pages/_error
wait  - compiling...
error - ./node_modules/@chakra-ui/portal/dist/esm/portal.js
Attempted import error: 'useCallbackRef' is not exported from '@chakra-ui/hooks'.
TypeError: (0 , _utils.compose) is not a function

Thanks ^^.
Quentin

Sidebar scroll behavior

Sidebar will scroll to top when clicked, it's unexpected.

Adding Buttons, Can't Add Chakra UI

Hi,

I can't add the buttons you have at the bottom of every page, and I can't add Chakra UI.

Routes Animations (Optional)

storybook build broken

../src/animations is missing in the stories

<ul> styling

Lists aren't styled too well imho, do you think there's any space for an improvements?

There's a huge whitespace between last paragraph (usually title) and the list itself.

MDX List rendering is wrong

This code in Dokz:

Renders to this:

But on a normal markdown renderer like github, this code:

And here is a numbered list:

1. Coucou
2. Toutou

And a nested bulleted list:

  - Lol Lol Lol Lol Lol Lol
    - Lol Lol Lol Lol Lol Lol
    - Yup Yup Yup Yup Yup Yup
      - Lol Lol Lol Lol Lol Lol
    - Yup Yup Yup Yup Yup Yup
  - Yup Yup Yup Yup Yup Yup
    - Lol Lol Lol Lol Lol Lol
      - Lol Lol Lol Lol Lol Lol
      - Yup Yup Yup Yup Yup Yup
    - Lol Lol Lol Lol Lol Lol
    - Yup Yup Yup Yup Yup Yup
  - Yup Yup Yup Yup Yup Yup

Should render to this:

And here is a numbered list:

1. Coucou
2. Toutou

And a nested bulleted list:

• Lol Lol Lol Lol Lol Lol
  • Lol Lol Lol Lol Lol Lol
  • Yup Yup Yup Yup Yup Yup
    • Lol Lol Lol Lol Lol Lol
  • Yup Yup Yup Yup Yup Yup
• Yup Yup Yup Yup Yup Yup
  • Lol Lol Lol Lol Lol Lol
    • Lol Lol Lol Lol Lol Lol
    • Yup Yup Yup Yup Yup Yup
  • Lol Lol Lol Lol Lol Lol
  • Yup Yup Yup Yup Yup Yup
• Yup Yup Yup Yup Yup Yup