Almanac.httparchive.org: Create a chapter config

[rviscomi]

When rendering a chapter page, we need to validate that the chapter exists (for the given year) and render metadata about that chapter including:

• part number (eg IV)
• chapter number (eg 20)
• title (eg HTTP/2)
• author(s) (eg [bazzadp])
• reviewer(s) (eg [bagder, rmarx, dotjs])
• _description_
• _hero image_

A config object should be created that lists all possible chapters for a given year. The object should define all of the metadata listed above.

Authors and reviewers must be referenced by their contributor IDs, which are defined in contributors.json.

• [ ] create src/config/2019/chapters.json create src/config/2019.json and combine chapter + contributor + team JSON into one file
• [ ] create a Python utility to load the config into memory and map contributor IDs to their metadata objects
• [ ] validate requests handled by the chapter router
• [ ] render metadata in the chapter template
• [ ] generate the table of contents in the outline template

[rviscomi]

@HTTPArchive/translators What do you think about this approach to generate the chapter metadata and Outline page based on the JSON config? I'm not sure how easy it is to translate using that process. Alternatively, we could create HTML files for every chapter and hard-code the metadata. Translating the HTML file would be straightforward and that would also take care of validation. The advantage to generating based on metadata is that we'd have one template for all chapters and a single source of truth for who authored/reviewed which chapters.

[c-torres]

I think the benefits of having _a single source of truth_ are better than focus on easing the translation process. In my personal opinion I like the proposed approach.

[mikegeyser]

If we manage to land #59, we could put some of this metadata (such as author/reviewer) in the metadata section of the markdown file. Is that something that could be interesting?

[rviscomi]

@KJLarson curious if you have any opinions about the organization of chapter URLs. A chapter page has the structure /2019/<chapter_id>. Should chapter_id be the numeric sort order, eg /2019/1 for the first chapter? Or a short identifier, eg /2019/js? Or the full title of the chapter, eg /2019/JavaScript?

[KJLarson]

Since none of the chapter names are that long, I would probably go with the full title. I think it would be the most informative. Also, if a person wanted to go back to something they saw about CSS, for example, I'm guessing it would be easier for most people to do that using the URL if the chapter_id were CSS because they wouldn't have to try to remember the chapter number.

[rviscomi]

Thanks, that makes sense. Any preference for casing and spacing? For example, MobileWeb vs mobileWeb vs mobileweb vs mobile_web etc.

[KJLarson]

Hmmm...I'm not sure about that one.

Are dashes an option? "mobile-web" is easy to read and type. "mobile_web" is easy to read, too, though it can be difficult to see underscores in certain contexts/fonts/etc. Casing probably wouldn't matter for these.

Personally, I don't have any troubles reading camel case or pascal case, but I'm not sure if that's the case (ha ha!) for everyone.

[mikegeyser]

What about titles that have non-alpha characters, such as HTTP/2? Would we turn that into http-2 or http_2?

[bazzadp]

What about titles that have non-alpha characters, such as HTTP/2? Would we turn that into http-2 or http_2?

In this case, I would choose http2 as it’s often used in URLs like that and in other places (e.g. Stackoverflow tag, Twitter hashtag). I’ve never seen the other two variants (http-2 and http_2) and they look odd to me tbh.

And while I’m giving HTTP advice my preference would be to make URLs case insensitive so people can use /CSS and /css. Especially if you are using the full chapter names specifically in the expectation that people will type them - don’t make them guess whether you’ve used camelCase or not by accepting both (though for SEO purposes you should probably 301 redirect to the definitive URL - lowercase would be my preference).

I would agree dashes over underscores as they are easier to type and much more common in URLs. Or even full words (mobileweb) as, in this case, we want the URLs to be easily guessed more so than easily read.

When you look at the current HTTP Archive report it uses a combination of things:
https://httparchive.org/reports/state-of-the-web#fontDisplay
The URL uses dashes (e.g. state-of-the-web), but the individual sections (e.g. fontDisplay) are camelCase. The URL is case sensitive though, on iOS Safari at least, the section is case insensitive. I would suggest following that precedent but with the added twist of making the URL case insensitive with redirects if possible.

[AymenLoukil]

From an SEO point of view for URL :

• lowercase
• dashes and no underscores
• no spaces and avoid special character

[rviscomi]

Great thanks everyone! (this is why I love having experts around 😄)