Get started fixes

[zemccartney]

Addresses https://github.com/hapipal/hapipal.com/issues/50

Relative to the list on that issue:

1. ✅
2. ✅
3. Updated at one point in the tutorial, appears most links were in place
4. ✅
5. ✅

Additionally,

• removed explanation of npx, given that tool is more commonplace (it was brand new at the time of original writing)
• added boilerplate's git project init command to top of the tutorial, to head off issues with applying flavors failing due to overwriting local changes
• updated route config method capitalization to match convention in example repo
• removed a handful of usages of the word "just"; realized it was brutally overused (to be clear, by me, my bad writing habit; to my ear at least 😛 )

Lastly, to the issue's suggestion of opening links in new tabs, this was a bit tricky: setting target=_blank within the markdown file didn't work; the attribute was stripped by Github's markdown API, which we use to process the file to HTML.

To workaround this, I experimented with 2 strategies, neither of which struck me as great, but both work:

• pre-process: as seen in lib/routes/getting-started.js, prior to passing the html received from Github off to handlebars, we process it by adding target="_blank" to all a tags
• handlebars: we lean into our usage of Handlebars by
  • use handlebars expressions to represent links e.g. {{link "here" "github.com/hapipal/examples/tree/master/paldo-riddles" true}}
    • the protocol is separated because otherwise, github translates the valid URL to an anchor element with an href attribute, on which the link helper chokes
  • handle these expressions with the link helper
  • compile these expressions within the html processed by Github via the precomp helper, which compiles the html before passing it off to our existing template to set as a normal expression; without this step, the expressions appear literally. Concretely, in getting-started.hbs, replace {{{html}}} with {{{precomp html true }}}

@devinivy some questions for ya:

• re: opening links in new tabs, are you cool with either strategy above? Or should I cut that work completely, cool to leave links as-is?
• Should I update all hapi documentation link in the tutorial (and elsewhere on the site) to hapi.dev, not API.md on github? Not crucial I know, but thinking to be consistent with how each repo directs users to hapi.dev
• I was thinking adding a seed, to create list of riddles, instead of depending on people to manually recreate their own could smooth out testing the later steps in the tutorial; how does that sound to you? I realized on reading back through that having to manually recreate riddles on server startup could annoy, if not trip people up. Another non-critical, thinking just as a nice-to-have

[devinivy]

Ay! Thanks for this, looks great and it will feel so good to resolve these.

re: opening links in new tabs, are you cool with either strategy above? Or should I cut that work completely, cool to leave links as-is?

I think we'll be stuck with a hack no matter what, since as you mentioned there's no support for this in GitHub markdown. My preference would actually be some post-processing on the frontend since I think it will be the most straightforward to understand and maintain. Something to this effect:

const markdownLinksExternal = () => {

    const links = document.querySelectorAll('.markdown-body a');

    for (let i = 0; i < links.length; ++i) {
        const link = links[i];
        link.setAttribute('target', '_blank');
    }
};

Should I update all hapi documentation link in the tutorial (and elsewhere on the site) to hapi.dev, not API.md on github? Not crucial I know, but thinking to be consistent with how each repo directs users to hapi.dev

If you are open to taking the time to do that, that would be awesome!

I was thinking adding a seed, to create list of riddles, instead of depending on people to manually recreate their own could smooth out testing the later steps in the tutorial; how does that sound to you? I realized on reading back through that having to manually recreate riddles on server startup could annoy, if not trip people up. Another non-critical, thinking just as a nice-to-have

I'm down with that, but if it would be simpler for the purposes of the tutorial to use file-backed SQLite persistence then that's cool too.

We can also pull any of these out into separate issues and address later if you'd like 👍

[zemccartney]

Alright, I think I addressed everything (thanks for all those detailed notes, btw! 🙏 )

• added link target post-processing, cleaned up prior junk
• switched all links to hapi and joi docs to point at their respective sites instead of github
• wrote up instructions for persisting data to a sqlite file (and pointed at the premade one in examples)
• tidied up the other suggestions

Though let me know if there's anything else that'd be good to address while I'm in here!