Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#13 2024-02-14 13:43:49

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,145
GitHub

Re: Textpattern docs site has moved to a new server

jakob wrote #336629:

Do I remember rightly, that this opens up the possibility to get docs search working again on Safari. Or was that a more involved process?

phiw13 wrote #336631:

The search functionality is still broken in Safari but iirc that required some code retooling, so not a regression.

Gather round, it’s story time.

The docs site used to run on MediaWiki back in the dark ages, and it was migrated to GitHub pages (hence the textpattern.github.io repo name). Since then, it has moved to our own self-hosted Jekyll instance, and more recently it’s moved to a new(er) server also running Jekyll.

On paper, Jekyll looks an absolute breeze to run: take some raw files, add a build recipe, and it spits out a heap of static HTML files. It’s great for blogs, and I’m sure it’s a really good solution for interactive site building where a person is involved.

Now, flip that on its head…I don’t want to be manually rebuilding our docs site on every commit…I want to set the server up to be as automated as possible, and the docs site comes down, gets built, and is deployed as smoothly as possible. This is what happens now, and it’s always a mess when I rebuild a server and deploy Jekyll:

  1. Install Ruby (global)
  2. Install Ruby Gems (to the non-root user that’s doing some of the heavy lifting)
  3. Modify the .bashrc so interactive shell stuff works for testing
  4. Set up & schedule the Bash script to grab the docs repo every 15 minutes
  5. Set up & schedule the Bash script to build the site with Jekyll
  6. Spend an hour wondering why it’s not building
  7. Spend an hour fixing missing / outdated Ruby Gems
  8. Spend an hour wondering why it’s still not building
  9. Remember that the .bashrc directives need to go into the Bash build script
  10. Cross fingers for another hour while it sort of splutters into life
  11. Remember why Ruby + Jekyll is zero fun.

Bam, that’s half a day gone. I don’t get on with Ruby admin’ing at all, and it’s only Jekyll that needs it…so there’s a trade off with not having PHP installed, so lower resource usage, but Ruby sort of infests all manner of stuff.

And I’m the person who compiles stuff from source, keeps a tight ship server-wise, and takes pride in a fleet of server cattle. Ruby and Jekyll feels like a bodge in the grand scheme. It may well be me being curmudgeonly over something that always makes me want to hurt inanimate objects and have a dozen or more browser tabs open to fix yet another Ruby error.

What I’d like to do is move away from Jekyll, if it’s viable. I’ve opened github.com/textpattern/textpattern.github.io/issues/212 for discussion with a view to:

  • selecting a hosted docs service like GitBook or Read The Docs
  • using their search, since it just works
  • doing some housekeeping on the repo to get it ready for the migration

To get Jekyll search working in Safari is possible, I’m sure…I lost most of yesterday to getting a new server set up with what appears to be mostly working Jekyll, and I need a bit of a break before I go splunking in the internals to get whatever bloody Ruby Gem is needed for search to work. Leave it with me.

(Thanks for coming to my latest TedX talk.)

Offline

#14 2024-02-14 13:53:05

wet
Developer Emeritus
From: Schoerfling, Austria
Registered: 2005-06-06
Posts: 3,324
Website Mastodon

Re: Textpattern docs site has moved to a new server

Pete, may I offer you a virtual pat on the back and a warm hug? I feel your pain. From the bottom of my heart – even though I only had to make a small Jekyll site once in my life.

Be strong. This too shall pass.

Offline

#15 2024-02-14 14:15:37

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,145
GitHub

Re: Textpattern docs site has moved to a new server

wet wrote #336648:

From the bottom of my heart – even though I only had to make a small Jekyll site once in my life.

The small sites are the worst since – if you’re like me, anyway – you’re dealing a constant, nagging “there has to be a better way to do this” in the background, whereas with the bigger sites you’re at least consigned to the fact that you have to do it with Jekyll since that’s how it’s always been.

And thank you. I appreciate that more than you know. I can’t tell you how frustrating it is not being able to be definitive on something, when all else in the chain is clear as a bell.

Offline

#16 2024-02-14 14:21:29

Algaris
Member
From: England
Registered: 2006-01-27
Posts: 535

Re: Textpattern docs site has moved to a new server

I keep hearing about Eleventy as an alternative to Jekyll. Apparently it’s built using JavaScript (Node.js), so no Ruby.

Also thank you for the hard work you’ve put into this. I’m constantly amazed at how much you do for the Textpattern ecosystem.

Last edited by Algaris (2024-02-14 14:23:16)

Offline

#17 2024-02-14 14:38:48

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,145
GitHub

Re: Textpattern docs site has moved to a new server

Algaris wrote #336650:

I keep hearing about Eleventy as an alternative to Jekyll. Apparently it’s built using JavaScript (Node.js), so no Ruby.

I had a poke around with Eleventy a while ago for another project, then looked at the NPM ecosystem that I’d need to grok and automate…and that gave me pause.

The lack of search is a pain, honestly. The irony of the docs being searchable text content for a CMS that has good search functionality (Textpattern) that’s using another entirely different CMS to display it without search functionality (my remix of Jekyll) is not lost on me.

In a future timeline, I’d love to see Textpattern be able to import a bunch of supplied, pre-formatted content and turn it into articles, images & files. We sort of have it a the moment with the setup article, but something beyond that to check for content in a given directory and then build the article scaffold…that’d be amazing.

I can bodge it with a scheduled SQL import, but that involves getting the articles from the repo, formatting them in a way that won’t snap a Textpattern instance in half, build the SQL, import it, and away we go. No Ruby. No NPM.

I’m not averse to hosting docs on a third party service that does it well. It frees up some of my time and energy to work on other things that don’t involve Ruby.

And thank you, I appreciate your kind words.

Offline

#18 2024-02-14 14:41:00

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,145
GitHub

Re: Textpattern docs site has moved to a new server

gaekwad wrote #336626:

I can power off the old server, save us some $$ and move to the next task.

This is now done. tarzan.textpattern.net is no more.

Next task: move servers to Debian 12.

Edit: this is scheduled to follow the release of Textpattern 4.9.0, so we can roll with Debian 12 + PHP 8.3. I don’t think I will have fully figured out PHP on Nginx Unit (we’re using PHP-FPM at the moment) by then, but who knows what the year will bring!

Last edited by gaekwad (2024-02-14 15:05:15)

Offline

#19 2024-02-14 14:45:27

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,281
Website GitHub

Re: Textpattern docs site has moved to a new server

Honestly, the only reason we chose GitHub pages in the first place was so the community could own the docs and we wouldn’t have to do it. Submit PR or request commit rights and away you go.

If that’s not on the table or uptake isn’t overwhelming there’s absolutely no reason not to up sticks to a Txp instance which can do it better.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#20 2024-02-14 14:49:14

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,281
Website GitHub

Re: Textpattern docs site has moved to a new server

And if we do move, I can feel a shell script running all the pages through pandoc coming on…


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#21 2024-02-14 14:55:28

etc
Developer
Registered: 2010-11-11
Posts: 5,064
Website GitHub

Re: Textpattern docs site has moved to a new server

gaekwad wrote #336652:

In a future timeline, I’d love to see Textpattern be able to import a bunch of supplied, pre-formatted content and turn it into articles, images & files. …

I can bodge it with a scheduled SQL import, …

One could also send this content to some etc_post entry point, that would then publish it as txp articles (passed via a md filter). And etc_cache could save them as static html files, that would be served when the search is not involved.

Anyway, thanks for your work and patience.

Offline

#22 2024-02-14 15:11:41

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,145
GitHub

Re: Textpattern docs site has moved to a new server

Bloke wrote #336656:

Honestly, the only reason we chose GitHub pages in the first place was so the community could own the docs and we wouldn’t have to do it. Submit PR or request commit rights and away you go.

Oh, I absolutely agree with the decision, Bloke – please don’t take my posts as gripes, far from it – GitHub Pages was basic and mostly worked until it didn’t, hence the move over to self-hosted Jekyll…we were 95% of the way there with GitHub Pages so it wasn’t a massive stretch to get over the line, it’s the underlying bullshit that’s a pain point.

Bloke wrote #336657:

And if we do move, I can feel a shell script running all the pages through pandoc coming on…

Totally! No need to reinvent the wheel. If and when I can wrap my noggin around GitHub Actions and the CI / CD tubes, there’s nothing stopping us having multiple versions spat out on each commit. EPUB docs coming to LeanPub in the not too distant future…

etc wrote #336658:

One could also send this content to some etc_post entry point, that would then publish it as txp articles (passed via a md filter). And etc_cache could save them as static html files, that would be served when the search is not involved.

This sounds far more elegant than my sledgehammer approach.

Offline

#23 2024-02-14 15:32:47

jakob
Admin
From: Germany
Registered: 2005-01-20
Posts: 4,611
Website

Re: Textpattern docs site has moved to a new server

gaekwad wrote #336652:

In a future timeline, I’d love to see Textpattern be able to import a bunch of supplied, pre-formatted content and turn it into articles, images & files. We sort of have it a the moment with the setup article, but something beyond that to check for content in a given directory and then build the article scaffold…that’d be amazing.

👍👍👍 Just wanted to thumbs-up this – but also the other follow-up ideas. If there’s an automatable path from PR-able docs to Textpattern, that would be great!


TXP Builders – finely-crafted code, design and txp

Offline

Board footer

Powered by FluxBB