Re: [tlug] TLUG Site with Hakyll Update

[Curt Sampson <cjs@example.com>]

On 2019-03-20 00:03 +0800 (Wed), Raymond Wan wrote:

> ...I previously kept notes for myself on a Mediawiki site.  Every
> time Ubuntu went through an upgrade, I'd have to update MySQL and
> every 2-3 updates, there would be some problem and I'd have to
> re-install some module.

Well, TLUG appears to have solved that problem. Nothing's been
upgraded since 2006! :-)

> If I remember correctly, I ran some plugin to Mediawiki and it did a
> dump of every page into a markdown file (I guess that is what you
> did, Curt?).

No, I don't have access to the server. All I've got at the moment is
HTML scrapes of all the pages. But Edward has started working on
getting the stuff out.

> I then gave up and realised (as was mentioned earlier) that the
> database was overkill.  I switched over to markdown and mkdocs [1]....
> As an aside, I also had an intranet work site using mkdocs. It
> doesn't look fancy, but I found it easy to set up.

Mkdocs looks pretty cool, actually. Though I've found things like even
that to be overkill if your repo is stored on a GitHub or GitLab
server: the server itself will happily render things (even images and
SVGs!) for you. I've even done a blog post with a comments section[1]
using this technique.

> I have this feeling it doesn't matter the static generator
> used.  Hugo is supposed to be based on Go, but unless you do
> something advance, I guess we don't use Go directly?

Basically that depends on whether they use an external or internal DSL
(domain-specific language) for the configuration. A language like Go
isn't so suited to build nice-looking DSLs embedded in the language
itself, which is why Hugo uses YAML or similar configuration files.[2]

Haskell tends to be fairly decent for embedded DSLs, so the
"configuration file" for Hakyll is just a Haskell program. It has
configuration statements that look like this:

    match "docroot/**" $ do
        route   dropInitialComponent  -- Remove /docroot from front of ouptut filename
        compile copyFileCompiler      -- Just copy the file as-is

    match "example/css/*" $ do
        route   idRoute               -- "Identity" route: ouput file has same name as input file
        compile compressCssCompiler   -- Compress CSS

You can see a bit of Haskell syntax leaking in (`$`, `do`) but overall
I think it's pretty near as readable as a designed-from-scratch
configuration language. (And much more readable than many
jammed-into-JSON-or-XML configuration languages!)

The real power of the embedded DSL is that your configuration language
is a real, full programming langauge, giving you all the power of that
when you need it. So, if your config file is embedded in, say, Python,
you can turn the rather tedious:

    site['foo'].name        = 'The Foo Site'
    site['foo'].icon        = 'icons/foo.png'
    site['bar'].name        = 'The Bar Site'
    site['foo'].icon        = 'icons/bar.png'
    site['baz'].name        = 'The Baz Site'
    site['foo'].icon        = 'icons/baz.png'
    site['quux'].name       = 'The Quux Site'
    site['foo'].icon        = 'icons/quux.png'

into:

    SITELIST = ['foo', 'bar', 'baz', 'quux', ]

    for s in SITELIST:
        site[s].name = 'The {} Site'.format(s.capitalize())
        site[s].icon = 'icons/{}.png'.format(s)

> Despite having a Github account with actual code, I've had little
> experience working with others.  I'm happy to pitch in and help a
> bit with the tlug web site, but prefer to be quiet at first out of
> fear of driving those of you who *have* worked with others on Github
> nuts...  :-)  Using Github or gitolite all by yourself is quite
> different!

Quiet is easy. Pull the repo but don't push anything back off your
development machine; nobody will even know you've ever made a change.

But at some point you're likely to want to be able to show someone
your changes, in which case you need to take the next step: forking
the repo.[3] That gives you your own copy, entirely separate from (but
related to) the official TLUG copy, so you can do basically anything
you want in there without fear of "polluting" or otherwise hindering
anybody else's work. If you do come up with a change you want to
propose for committing to the `master` branch of the main repo, you
just put that change in your repo and do a pull request[4] and, after
discussion or review, hopefully you have now contributed something!

(For developers familiar with the whole Git and branching process,
it's probably easier just to ask to join the TLUG Website team[5],
giving you the ability to push to the tlug/tlug.jp repo, and then just
work on branches directly in that.)

[1]: https://github.com/0cjs/py-allthesame
[2]: https://gohugo.io/getting-started/configuration/
[3]: https://guides.github.com/activities/forking/
[4]: https://guides.github.com/activities/forking/#making-a-pull-request
[5]: https://github.com/orgs/tlug/teams/website

cjs
-- 
Curt J. Sampson      <cjs@example.com>      +81 90 7737 2974

To iterate is human, to recurse divine.
    - L Peter Deutsch