Thank you for using GitBook with us!

[addisonschultz]

Hello @das-g @ekohl 👋

Addison here from GitBook—We hope you’re doing well! I recently came across the Django Girls tutorial book you and the team have been using, and have to say I’m definitely impressed! We love to see some of the diverse ways GitBook is being used across tech communities.

I noticed though, that the book you’re on is still using and older version of GitBook - I’m not sure if you’ve seen, but we’ve released a newer version of GitBook, and wanted to see if you’d like to know more about switching to the new one.

To make things easier, I’ve already done the entire migration for you from a fork of this repository, so you can check it out how it looks here: https://djangogirls-2.gitbook.io/tutorial/

The new version of GitBook comes with all of the same features as the version you’re already using, plus a ton more—And we’ve got a lot of amazing features coming in the near future (Like our AI powered search launching later this month!)

Another advantage of using the new version would also be that your team can quickly use the GitBook UI to make changes to content through change requests, and still have all the updates stored in GitHub inside the main repository.

I saw an issue recently on exporting and using GitBook for e-books, and wanted to highlight that migrating to the new version of GitBook still allows you to keep GitHub as your source for the content - so any workflows you might already have around using Git to manage your source will still be in tact - you'll just gain a lot of extra functionality on the published side of things!

I’d love to help you and the team migrate to the new version—It’s only a few steps you need to do on your side, and I’m happy to hop on a call to walk you through it all if needed!

Would love to know your thoughts, so feel free to chat here, or over email if it's easier 😄

Looking forward to hearing back,

Addison
Developer Relations @ GitBook

[ekohl]

Hello @addisonschultz,

We've switched over to honkit because it was easier than converting, though I think there was an additional repo where a slightly different path was chosen. It would certainly be good to unify.

To make things easier, I’ve already done the entire migration for you from a fork of this repository, so you can check it out how it looks here: https://djangogirls-2.gitbook.io/tutorial/

When I look through that I miss a lot of content. For example, all the code blocks are missing for me in the installation section (https://djangogirls-2.gitbook.io/tutorial/installation). https://djangogirls-2.gitbook.io/tutorial/django_installation also misses all content compared to https://tutorial.djangogirls.org/en/django_installation/

Perhaps this is because I use umatrix which blocks requests to third party sites by default, but this looks like the migration still needs a lot more work. Work that I'm afraid I don't have time for now.

So I'm open to the change, but I can't spend too much time on it so others would need to drive it.

Something that would be very welcome is if you can have a selector on the examples. We have instructions for Windows, Linux & Mac. The tutorial would be a lot easier to follow if you could select one at the beginning and then only show the instructions for your OS.

Today this is something we could actually write ourselves, since honkit is open source and you can write plugins. How would we do such a thing with GitBook?

[addisonschultz]

Hey @ekohl, that definitely makes sense why some of the snippets aren't picking up the include files—It's not parsing it as you'd like through the markdown parser we're using.

Also understandable on the time investment on switching to something like this. While it's minimal, it would require someone to help drive this as you mentioned.

The last 2 points you mention are quite interesting though. Right now, we're working on our Integrations Platform, which will greatly allow you to customize the way you would like to use GitBook.

In a nutshell, we have a REST API, a framework for building custom blocks/elements, and Visitor Authentication (dynamic docs in the near future).

The last point on Visitor Authentication would allow you to have custom docs for different users (based on OS, or whatever else you would like) - Basically you can pass JWT data to the client and dynamically show/display data in your docs depending on the conditions you set up. We have an old prototype of this working, and will continue to work on this even more after we get the V1 of our platform launched (within the coming month/two).

The Integrations Platform also will let you create plugins/custom blocks, leveraging certain GitBook Runtime APIs and access to other custom elements.

We have the docs here, if you wanted to poke around and explore what we're working on!

https://developer.gitbook.com/

Again it's understandable not being able to make the switch now, but hopefully some of these coming features (along with product improvements) over the coming months gives you and the team some things to think about!

Feel free to use me if you're ever interested in exploring or learning more, I'd be happy to help. Or, if you have any additional feedback for us on the product or Integrations Platform, we're all ears!

Cheers,
Addison

[das-g]

Both, as a general principle, and more especially specifically after #1652, I'd like to avoid any vendor lock-in in the future.

If I'm understanding correctly, to make the tutorial compatible to the current GitBook system, some changes to the Markdown files would be needed. I assume (and hope) the content would nonetheless be in a format that can be modified not only on the GitBook platform but also (and still sufficiently conveniently) by editing the files as plain text in any local editor. Though, could the tutorial still also be rendered independently of the GitBook platform into an acceptable representation for the readers, preferably using a fully FLOSS stack / pipeline?

If not, I'd vote for sticking with HonKit or, if at all, switch to another FLOSS static site generator.

[ekohl]

Like @das-g I also highly favor a FLOSS stack. Buying into a proprietary system is something I don't do out of principle. It also makes it much harder when you can't try something out locally. Perhaps I'm old fashioned, but anything I can't do offline is something I distrust. If a vendor goes away (like we had with #1652), it is very disruptive. And you effectively destroy your investment because nobody else can take it over. Unlike with FLOSS there's no way to fork a service.

I'm very thankful for GitBook for making the initial version open source, which allowed HonKit to continue serving us with minimal effort, but the current version of GitBook doesn't look attractive to me.

[addisonschultz]

Hey both,

I get it, and the context around why you'd like to stay using HonKit is definitely understandable. Just to answer some questions above, GitBook now gives you the UI and hosting for the content you keep on GitHub—So you'd still be able to edit, push, and merge changes locally or remotely and see them updated in the GitBook UI.

That being said, @ekohl is right in saying that you won't get a local version of the GitBook UI. Again it's understandable how HonKit is a better option for you given the way you're using it, but we would like to say thank you regardless for using GitBook alongside us!

If you do ever have questions for us in the future, you're welcome to reach out