Set up docs self-hosting

[petecooper]

There's a growing need for self-hosting of docs for enhanced flexibility (see also #79).

Dibs. R&D phase.

[Bloke]

cough Textpattern instance with smd_ebooks for creating offline content cough

(The plugin will need tweaking for 4.8)

Honestly I can't see anything in Jekyll we can't do better or more efficiently in Txp. We have articles in sections, permlinks, markup, better search, header/footer, includes that are more flexible via forms and shortcodes, ...

Run the Jekyll pages through pandoc to convert from Markdown to Textile, or install Markdown as a textfilter and just port the content as-is.

If we can squirt collaborative changes from the GitHub repo to the Txp filesystem to rebuild the DB as part of a git post-commit hook or CI pipeline, we should be able to rebuild the changed docs with some script-fu.

[petecooper]

@Bloke - I'm inclined to agree. I'm learning CI + Pandoc at the moment, so we'll see what the new year brings.

[wion]

Considering the relatively low volume of docs content (and let's recognize that as by design), and the greater control Txp would provide over includes, URL redirecting, etc. I have to agree.

You could even do a flat-file site and keep it under version control. Version control is a nice thing, actually.

I don't think it's important to convert Markdown back to Textile, since we already went through that dance of going the other way. Screw that. Just add wet_markdown and use Textile for new docs only, if that's really a big deal.

That said, I don't want anything to do with the actual migration process. I know I've been in 'beast-mode', as Pete put it recently, but I'm just trying to make up for where I dropped the ball a few years back, get broken/lagging docs completed and improved. And I recognize some other editorial needs I'm happy to give attention to, to stabilize. But I'm aiming to get back to much less 'beast-mode', as it were. My objective here is get the content architecture square and then put myself on editor cruise-control so that I can return energy to my own writing.

So as long as this doesn't create any additional work for me that I haven't already shouldered myself, I have no objections.

[petecooper]

Thanks @wion - I do not want to create any additional work for anyone, and certainly not undo any work done.

[philwareham]

So.. you'd need to:

1. Keep articles as flat files (still on GitHub) and somehow inject direct to DB, so they can still be version controlled? Keeping version control is essential here.
2. Change wet_textfilter_markdown from Markdown Extra to Kramdown instead (or build a new plugin, I assume)

If those hurdles can be overcome, I'm interested.

[petecooper]

Keeping version control is essential here.

This is what's keeping me away from Textpattern as-is. On the one hand - yes - CMS, and we're literally managing content here, but on other hand, it doesn't feel like the right tool for the job.

Something more automated would be better, I think - even a self-hosted Jekyll in the first instance would be minimal effort to get going an replicate the GitHub delivery but with redirect trimmings and other stuff.

Flat files, static site generator, version control baked-in, make it wicked-fast, spit out compiled versions (EPUB, PDF, MOBI, etc) as part of the GitHub CI job, rinse and repeat.

(Edit: just my 2c, of course.)

[Bloke]

Suits me fine. If self-hosted Jekyll (or equivalent) is an option then go for it. I only mentioned Txp since it seemed like a good fit, but I'm by no means married to the idea if the obstacles are less than optimal to overcome. Go with whatever is easiest, most flexible and allows us to retain version control.

[philwareham]

Suits me fine. If self-hosted Jekyll (or equivalent) is an option then go for it

Sounds fine to me too, would be handy to use proper Jekyll plugins and proper SSL, redirects, etc. instead of the locked-down GitHub Pages version of Jekyll. I have no idea how best to achieve that but a quick web search brings this...

https://styxit.com/2017/09/13/self-host-github-pages-on-digital-ocean.html

If someone wants to have a stab at it then please go ahead. :)

[petecooper]

If someone wants to have a stab at it then please go ahead. :)

Dibs. Won't be for a while, but I'll take it.

[philwareham]

Short-term (before we potentially move to self-hosted Jekyll), GitHub now allows you more control over your Jekyll site as long as you deploy with GitHub Actions.

See https://jekyllrb.com/docs/continuous-integration/github-actions/

This now allows for third-party Ruby plugins and other customisations over and above the restricted GItHub Pages builds.

Will investigate at some point in the future.