search

amiroff / NextBook

NextBook is quick and easy way to build technical books or documentation with markdown that run blazingly fast.
https://next-book.vercel.app
MIT License
228 stars 34 forks source link

Using NextBook as a tool or with external pages? #11

Closed mrieser closed 3 years ago

mrieser commented 3 years ago

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.

amiroff commented 3 years ago

Hey Marcel,

Thanks for feedback. We are on the same page and I am definitely feeling the need to address these issues.

Regarding pulling upstream changes, I just pushed an update where users can now create their own pages/ directory, copy src/pages/_app.jsx file over and start creating content files. Also moved many settings to environment variables, so you would only have conflicts with config.json file when pulling upstream. I hope this eases the pain and I plan to do some more work regarding decoupling configuration. I guess making this whole project a template for an npx create command would do it, need to research though. 🕵️‍♂️

Regarding multiple books support, the easiest way would be to nest in pages folder:

While this would solve the content problem, title and left navigation menu would still need a refactor to support multiple titles. I'll see what I can do regarding this.

amiroff commented 3 years ago

OK, so here it is:

yarn create next-app my-awesome-book -e https://github.com/amiroff/NextBook/tree/master/template

Running that will behave just like Jekyll, ie, create you an app with latest template code.

Everytime you run this, you get up-to-date code for new project. This way you can create new projects for every book I guess.

amiroff commented 3 years ago

Btw, currently there are problems when bootstrapping project with npx, due to unmaintained dependencies, will push a fix soon so that npx create-next-app my-awesome-book -e https://github.com/amiroff/NextBook/tree/master/template is also possible to use.

amiroff commented 3 years ago

As of now, above command also works.