amiroff / nextbook Goto Github PK

NextBook is quick and easy way to build technical books or documentation with markdown that run blazingly fast.

License: MIT License

JavaScript 74.64% CSS 8.09% MDX 17.28%

mdx nextjs gitbook react documentation-tool documentation-generator nextbook buid-technical-books lighthouse-score seo

nextbook's Introduction

NextBook is quick and easy way to buid technical books or documentation that support modern standards and run blazingly fast. It works by compiling markdown and MDX to static pages. This way, first content render on user's device is near instant.

NextBook makes writing technical docs stupid simple while keeping featureset minimal but open for further extension.

Primary Features 🧿

💅 Good looking, simple and readable UI based on tailwindcss including dark mode and auto-centered layout,
🌎 Great SEO out of the box,
📱 Mobile & printer friendly,
🚀 Single page application with pre-fetching,
🧾 Easy content creation with markdown and MDX support,
💻 Something more than what basic fenced code offers. Like line highlighting, linking to source and copying to clipboard,
🤓 Familiar Git workflow and collaboration,
⌨︎ Keyboard shortcuts for frequently used actions (theme change, page navigation),
🔎 In-page optional table of contents with scroolspy,
© You own your data, code is the data. Committing to repository and seeing results in the simplest form,
🏎 Fast to get started, just one command for up & running locally,
🎊 One click (or push) deployment,
🛠 Unlimited dynamic features can be added with MDX,
⚙︎ Customisable, extensible and simple codebase,
❤ Built on open-source,
👍 And many more small details...

With the advantages of Next.js and React anything fancy (grading, level switching...) can be added along the way.

What's New In NextBook 3.0?

This release contains major speed improvements and backwards incompatible changes. Most of these come from MDX2 removing some functionality and other old libraries still not supporting ES modules.

Migrated to next-mdx-remote v.4 which now uses MDX2. This has some speed improvements and stricter MDX syntax checking. See MDX2
Replaced some custom incompatible markdown plugins with MDX counterparts. These are:
- Subscript: was ~, became <sub> tag.
- Superscript: was ^, became <sup> tag.
- Mark (higlight): was ==, became <mark> tag.
- Changed syntax for Accordion and Tabs components. See related documentation.
Removed functionality
- Indented code. This was removed from MDX2. Use other ways to define fenced code blocks.
- Linking with angle brackets: This was removed from MDX2. Use other ways to define links.

What's New In NextBook 2.0?

Support for multiple books in one project.
Design based on tailwindcss.
Markdown content is now being loaded with next-mdx-remote. This means content is now separated from routed pages.
Auto-centered layout on big resolutions leading to one less configuration option.
40% smaller bundle size.
Navigation bar.
Refined mobile UI.
Less code (−4,000 LOC).

Getting Started

Having Node installed beforehand, bootstrap a new project with npx create-next-app my-awesome-book -e https://github.com/amiroff/NextBook
Run npm run dev:watch and open http://localhost:3000/
Check documentation to see what's possible with NextBook.
Create your markdown or MDX content in content folder. Pages should auto-refresh as you modify markdown content.
Update config/config.json with your table of contents and other information.
Update pages/index.jsx to suit your needs as a standalone landing page or as a redirect to content.
Deploy your respository or export (npm run export) and copy your content to any static hosting provider like Vercel, Netlify, Github Pages or Google Cloud.
Have fun! 🎉

This should be enough to have a statically generated documentation page/book.

nextbook's People

Contributors

Stargazers

Watchers

nextbook's Issues

npm run export not working

Hello

I ran npm run export but the execution remains stuck on Creating an optimized production build.

Any thoughts?

What's the bare minimum command to run to get static content ?

Hello,

I am a bit confused. I can run npm run dev:watch and get something on http://localhost:3000 but how do I export this to static pages ?

So I could just copy those pages to apache, nginx, S3, etc. ?

npm run build seems to build something but the current folder don't have any new files or directory. npm run export complains about page "/" and says to consult next.js help.

Thanks :).

Synchronized tabs

For example, in https://developer.android.com/topic/libraries/app-startup#kotlin you can select a programming language and all tabs sync to it. Is that realistic here, too?

Q&A: i18n Feature

Hello. Can you help me about i18n, please? Will this project include i18n features into the source code?
Thanks!!!!!!

Widescreen boxing

When having the NextBook page open on a widescreen it currently looks like this:

The font gets bigger as well which looks a little wierd in my opinion.

Would it be possible to box this in? (Like GitBook for example)

"npm run dev" not working

I installed nextbook and run

npx create-next-app your-blog --example "https://github.com/wutali/nextjs-netlify-blog-template"
npm run dev

error message

Error: Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:

You might have mismatching versions of React and the renderer (such as React DOM)
You might be breaking the Rules of Hooks
You might have more than one copy of React in the same app
See https://reactjs.org/link/invalid-hook-call for tips about how to debug and fix this problem.
at resolveDispatcher (C:\Intellij\projects\nextjs\yoonco-book\node_modules\react\cjs\react.development.js:1476:13)
at useState (C:\Intellij\projects\nextjs\yoonco-book\node_modules\react\cjs\react.development.js:1507:20)
at ThemeContextProvider (C:\Intellij\projects\nextjs\yoonco-book.next\server\pages_app.js:1338:61)
at processChild (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\react-dom\cjs\react-dom-server.node.development.js:3353:14)
at resolve (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\react-dom\cjs\react-dom-server.node.development.js:3270:5)
at ReactDOMServerRenderer.render (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\react-dom\cjs\react-dom-server.node.development.js:3753:22)
at ReactDOMServerRenderer.read (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\react-dom\cjs\react-dom-server.node.development.js:3690:29)
at renderToString (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\react-dom\cjs\react-dom-server.node.development.js:4298:27)
at Object.renderPage (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\next\dist\next-server\server\render.js:54:851)
at Function.getInitialProps (C:\Intellij\projects\nextjs\yoonco-book.next\server\pages_document.js:841:19)
at loadGetInitialProps (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\next\dist\next-server\lib\utils.js:5:101)
at renderToHTML (C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\next\dist\next-server\server\render.js:54:1142)
at runMicrotasks ()
at processTicksAndRejections (internal/process/task_queues.js:93:5)
at async C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\next\dist\next-server\server\next-server.js:109:97
at async C:\IntelliJ\projects\nextjs\yoonco-book\node_modules\next\dist\next-server\server\next-server.js:102:142
warn - C:/IntelliJ/projects/nextjs/yoonco-book/node_modules/@babel/runtime/helpers/arrayLikeToArray.js
There are multiple modules with names that only differ in casing.
This can lead to unexpected behavior when compiling on a filesystem with other case-semantic.
Use equal casing. Compare these module identifiers:

C:\IntelliJ\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\arrayLikeToArray.js
Used by 2 module(s), i. e.
C:\IntelliJ\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\unsupportedIterableToArray.js
C:\Intellij\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\arrayLikeToArray.js
Used by 2 module(s), i. e.
C:\Intellij\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\arrayWithoutHoles.js

C:/IntelliJ/projects/nextjs/yoonco-book/node_modules/@babel/runtime/helpers/arrayWithoutHoles.js
There are multiple modules with names that only differ in casing.
This can lead to unexpected behavior when compiling on a filesystem with other case-semantic.
Use equal casing. Compare these module identifiers:

C:\IntelliJ\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\arrayWithoutHoles.js
Used by 1 module(s), i. e.
C:\IntelliJ\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\toConsumableArray.js
C:\Intellij\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\arrayWithoutHoles.js
Used by 1 module(s), i. e.
C:\Intellij\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\toConsumableArray.js

C:/IntelliJ/projects/nextjs/yoonco-book/node_modules/@babel/runtime/helpers/assertThisInitialized.js
There are multiple modules with names that only differ in casing.
This can lead to unexpected behavior when compiling on a filesystem with other case-semantic.
Use equal casing. Compare these module identifiers:

C:\IntelliJ\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\assertThisInitialized.js
Used by 2 module(s), i. e.
C:\IntelliJ\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\possibleConstructorReturn.js
C:\Intellij\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\assertThisInitialized.js
Used by 1 module(s), i. e.
C:\Intellij\projects\nextjs\yoonco-book\node_modules@babel\runtime\helpers\possibleConstructorReturn.js

Nested Folders in TOC

It would be nice if there is support for nested folders in the sidebar/toc.

Using NextBook as a tool or with external pages?

If I were to use NextBook in the current setup, I would fork the repo and start replacing the files in the pages directory. I could then commit my pages to my fork. But as soon as you update NextBook and I do an upstream pull, chances are that there will be merge conflicts. Also having multiple books would not work well as one can only fork a project once, I think. Thus working on multiple books quickly becomes a maintenance nightmare, or they would be stuck with whatever version of NextBook was used when the project was set up.

Is there a way to use NextBook like an external tool? (e.g. like Jekyll, Hugo, ...) So it can be updated on its own, while the content it works on is in a separate repository?

Maybe NextBook can somehow be configured to use a different config and pages-directory? E.g. something like npm run build --work-dir=../my-book/? This would already help a lot.

I really like the output that NextBook produces and the rich feature set, but I don't yet feel confident that it fits in my workflow.