documentation building instructions missing

[aspiers]

The README.md in this repo is quite nice and detailed, but it omits one crucial detail: how the documentation is rendered into an HTML website. This is problematic because contributors need to be able to test how their proposed doc changes render. Ideally this would be possible to do locally before submitting any PR, to avoid wasting other people's time reviewing changes which aren't yet rendering correctly. But at very least it should be possible to check the rendered version of the PR via the output of a CI job. I've filed #311 regarding the latter.

[RCheesley]

I'd like to know this as well! It can be a bit hit or miss otherwise, especially with new pages!

[RCheesley]

I did a bit of snouting around and came across this https://github.com/GitbookIO/gitbook-cli - maybe we can incorporate this information in the Contribution file, what do you think @virgilwashere @aspiers ?

[virgilwashere]

That's legacy.gitbook I found out....

[aspiers]

Yeah, sadly GitBook no longer uses git natively:

https://docs.gitbook.com/faq#how-do-i-access-my-gitbook-repository

For me that feels like enough of a facepalm to motivate moving off their platform entirely. Even if moving away from an Open Source industry standard onto something proprietary might be palatable or sensible for some, I don't think it's appropriate for an Open Source project like Mautic to follow them down that road. I expect the community would prefer to avoid locking documentation into a proprietary system.

[RCheesley]

Ah, that's a pain, but in some ways positive given all the challenges we've been facing recently!

There are some options I was looking into if we feel we want to retain a git-based documentation project, or we can look to other collaborative tools. I was poking about a bit on Mediawiki for a while to see if that might be an option.

Let's start a thread on the forum and talk about it there to open up the discussions!

[virgilwashere]

Ironically, I've just worked out most of what's required to serve a gitbook locally for testing.

# personally, I use yarn, but meh.
npm install gitbook-cli svgexport -g
gitbook build
gitbook serve

And to add emoji to gitbook:

npm install gitbook-plugin-advanced-emoji
vi book.json
# "plugins" : ["advanced-emoji"]
gitbook install
gitbook serve

[virgilwashere]

Let's start a thread on the forum and talk about it there to open up the discussions!

FWIW, https://docsify.js.org/ is floating my boat right now, after 15 minutes.

Didn't get to

• [ ] https://rust-lang.github.io/mdBook/
• [ ] https://daux.io/Features/Table_of_contents.html

[RCheesley]

https://forum.mautic.org/t/documentation-platform-s/11566 I started a discussion here :)

[RCheesley]

Hi folks, closing this issue as we now have the new docs platform deployed, no building required! :tada: :rocket: