Make toml.io!

[workingjubilee]

It's 1.0 time, and the website is a critical path item according to https://github.com/toml-lang/toml/projects/1 so let's open a tracking issue and see where we are? I'd be happy to get started on this, but I don't know if anyone's secretly been writing stuff for it yet.

---

Edit by @pradyunsg

There's WIP website here: https://wip--toml-io.netlify.com/v1/en/

[pradyunsg]

@workingjubilee Appreciate the interest! @LongTengDao has expressed interest in this as well.

I had started to tackle this myself but ran out of time. Also, well, doing everything myself is not a good idea. ^>^

On that note, find my notes below:

---

toml-lang/toml -- development space.
toml-lang/toml.io -- where the versioned specifications live.

Structure

• / has the objective and example:
  • Link to "current" specification, with version number.
  • Links to the compliance test suite and Wiki.
• /v/
  • List of all versions of the TOML specification.
• /v/<version>
  • Specification text for that version, with link to ABNF (if it exists).
• /v/<version>.abnf
  • ABNF for that version, exists for all post-1.0 versions.
• /v/current (maybe?)
  • Redirects to the latest version of TOML.

TODO: What'll be the "release process" for future versions of TOML and document in README of toml.io? Automate so that it's 1 CLI command.

Maybe:

• copy toml.abnf & specification.md to toml-lang/toml.io
• rename
• git tag

Design

Follow aesthetic of posts on https://pradyunsg.me/blog. Skip any bikeshedding unless @BurntSushi or @mojombo holler.

[pradyunsg]

I realize now that that doesn't consider translations -- I guess, let's have the the translations namespaced, under /<2-letter-lang-short-code>/.

[rwitzel]

What is the benefit of toml.io? Developers like GitHub.com.

Isn't it better to focus on the remaining blocker #631 ?

[LongTengDao]

some suggestion

repo-root/src/ # could we write site source with .toml? to detach data and view, and nice diff
repo-root/build/ # view template and style defination, and build script
repo-root/docs/ # dist to here to get github pages support
repo-root/dist/ # pdf and/or offline single file html hand book

# site-root = repo-root/docs
site-root/ # dont display whole spec, lively introduce and links will be better
site-root/v/ # versions list and change log
site-root/v/?lang=
site-root/v/1.0/spec/
site-root/v/1.0/spec/?lang= # an edition surfix maybe better than pre ns, because not all path has it's translation, like abnf
site-root/v/1.0/abnf/ # a highlighted html page will be better than a raw .abnf file
site-root/v/1.0/edit/ # online toml highlight/mindmap editor
site-root/v/1.0/view/ # online toml highlight/mindmap viewer
# all path hide the .html tech details

url may be the only thing can't change easily in the future (people will link our site)

[LongTengDao]

@rwitzel maybe a offical website born with 1.0 will be good opportunity to disseminate TOML

[pradyunsg]

TOML developers want TOML 1.0 to have a better home than github.com/toml/toml-lang. This also enables freeing the toml-lang repository from the additional overhead of holding releases in-repo.

That's a good enough reason for me to spend my time to work toward it, and collaborate with others on the same.

Anyway, the issue you've referenced is also progressing so, tbh, I'm not sure what you're suggesting here. :)

[pradyunsg]

/v/1.0/spec/?lang=

That's not gonna work with a static website.

reg: multiple formats

Well, that depends on the static site generator we use. Something like Sphinx is fully capable of generating docs in loads of formats, from html to epub.

[mojombo]

I've been working on some ideas for a TOML website with @cannikin, who is now working with me at Preston-Werner Ventures on experimental projects. He should have some capacity to help move TOML forward from now on! I'll make sure he posts them here when he's back tomorrow.

[rwitzel]

@pradyunsg You guys are doing awesome work and it is highly appreciated. My point: I don't understand why the website is critical for TOML v1 (sorry for not mentioning/clarifying that in my previous comment) - as indicated in the project board. But, yes, you mentioned that it increases visibility and this is true, for sure.

[workingjubilee]

As the formal "stable" release, it would be nice if we also were able to pick up a bunch of momentum from declaring 1.0 and get even a tiny bit of social buzz, not only to get people to notice there's an alternative to Yonder Ambitiously Maximalist Language, but to prompt updates to existing parsers and make sure they're in conformation. Not much changed through 0.5, but some are still behind, and saying "we're 1.0!" at the same time as "and we have a site! It's not awful to look at!" would be helpful.

[cannikin]

Hello all! I started comping up a homepage last week:

And a different color scheme:

I envisioned the links at the top being:

• [code] -> GH repo
• [spec] -> basically the README formatted to match the site (could include links to previous versions as well)
• [validate] -> @mojombo wanted to include a validator so you could test your implementation

The [try it] area lets you convert JSON <-> YAML <-> TOML.

[pradyunsg]

This looks great @cannikin! I'll refrain from nitpicking. 🙃

@mojombo wanted to include a validator so you could test your implementation

@mojombo Do you see this as different from toml-lang/compliance? My understanding is that it'd be the validator but it'd be good to confirm.

[cannikin]

@pradyunsg haha If there's anything big missing and/or wrong please let me know! Otherwise I'll assume it's perfect ;)

[pradyunsg]

@cannikin some of the broader concerns:

• I'm not sure about on the comparing with YAML and JSON in the landing view. "It's obvious" doesn't need to be said in comparison to the other languages. Doing that feels a little... arrogant? None the less, since we already have a "try it" at the end of page, we can get away without this on top of the page.

• translations. TOML has folks translating the specification to other languages, which is a good thing. We should present these on the website, in a discoverable manner. :)

  Ideally, all pages are translation capable but just the specification is also good enough for starting IMO.

[LongTengDao]

@cannikin looks great!

Do you think JSON5 deserves a comparison?

[cannikin]

@LongTengDao Absolutely, I've never actually used JSON5 myself but if everyone thinks it's popular enough let's include it! Were you thinking a comparison at the top or as part of the "try it" section at the bottom?

[LongTengDao]

@cannikin Hi,

JSON5 is an advanced JSON-like alternative, just like TOML to INI, so I think there is no need to display them at the same time.

If at the top, JSON5 vs YAML vs TOML would be ok (if the sample has comments to compare, that's fair).

If the sample has no comments like now, then the top should be JSON vs YAML vs TOML. (because JSON is more widely used.)

The other one just add into the bottom, because the top area is expensive.

In fact, I think XML is also typical enough for compare in the top, but your current design is so beautiful, if add 3 to 4, will it be ugly?

[cannikin]

@LongTengDao Yes I thought the same thing—3 along the top looks great, 4 won't balance as nicely.

[workingjubilee]

I like it.
I favor the warmer color palette. Might warrant tweaking the palette of the syntax highlighting to complement. It overall feels nice as-is, and stands out from the default white/black/blue of the Internet. Both do, actually (the first is blue/black/white, which actually matters a lot in terms of visual engagement).

Amusingly a warmish palette would actually be something shared with the other format sites... compare https://yaml.org/ and http://json.org/ with this. This mock is a lot nicer and more coherent on colors, though, and it's not like they're sharing hex codes.

If the buttons at the top are going to be the primary route to the spec, then it would be best if they were more eye-catching. ( Imagine the bleary-eyed programmer staring at the site at 1 AM. ) Unsure about what the current mock would actually pan out to in that regard, since at least some of that is about interactiveness.

I could see myself liking the "try it" being on its own page, as well as embedded here (so that there's a page where it comes first, mostly). Hm, How many formats would it offer conversion to/from? If just a few, radio buttons maybe?

[cannikin]

Updated comp! Used some feedback from above, tweaked colors a bit, etc, etc.

[LongTengDao]

I think the the top half part of the first draft is more clear, and make toml center & bigger will obstruct users compare, that's not necessary, because toml being the best is an objective conclusion ;) while json->yaml->toml hinted at the order of evolution. 3-description-text-closing-and-align-to-top-3-samples which not one-to-one correspondence infact is also not intuitive.

But this is just my personal opinion, it depends on you, there are trade-offs and considerations in any scheme.

One place maybe a typo, datetime in toml sample is a string. And toml only has one kind of four datetimes could has offset. And there are no null type in toml. (null is no use in toml design, this is not a imperfection, but the description should be preciseness.)

Of cause, thiese are minor text content layer problems which could be improved by PR, never mind, just as a memo.

Anyway, our design is way ahead of other languages' offical sites. Cheers! Looking forward to come online.

[mojombo]

@cannikin I think it would be a good idea to start with some mobile designs first, it might help us really focus in on what's important for the home page. Then we can see how that translates to a desktop design.

[workingjubilee]

I agree that relying on people reading left-to-right (on desktop) is way better than popping the TOML view front-and-center, and I think it translates better to mobile (since in portrait view on my phone, I would just scroll down).

TOML already has a better syntax highlighting rule making it immediately stand out. ^_^

A subtle stagger or embiggening would be OK. Less ostentatious while still emphasizing. I think saying "it's obvious!" is OK, though, but I would almost save it for a deeper explanation (anatomy of a TOML file?) page. I think I might take a swing at showing what I mean there.

[cannikin]

CHECK IT http://toml.camerontech.io/

The styles are only optimized for mobile right now so open on your phone and/or responsive Chrome. And interaction stuff isn't hooked up. (23-Aug) Hooked up the snippet tabs at the top!

If you want a quick preview:

[cannikin]

After a discussion with @mojombo I've updated the homepage with more of a focus on TOML features and less on how other formats are garbage. Check it out! https://wip--toml-io.netlify.com/

[pradyunsg]

more of a focus on TOML features and less on how other formats are garbage.

I'm super happy with these changes here. :)

Also... on the use of (verbose) language directly from the specification -- we should probably use more concise language and examples here. That'll also help make that section smaller and a quicker tour. ;)

[cannikin]

Also... on the use of (verbose) language directly from the specification -- we should probably use more concise language and examples here.

Yeah I tried to paraphrase into less technical language in many places but I left most of the code examples as-is since they really show the flexibility of TOML's syntax. We could trim those down if we think people's eyes will glaze over. Let me know which examples are cuttable!

[pradyunsg]

nit: padding at the end of the "quick tour" section.

I can come up with the content for the "quick tour", over the weekend. Lemme know if that's cool/not cool. :)

[cannikin]

@pradyunsg haha yeah I saw that earlier and hoped no one would notice until I had a chance to fix. ;)

It is very cool if you want to take a stab at the quick tour content!

[workingjubilee]

While I agree it's a mostly superfluous modification to the README, in principle it should be harmless because a Markdown parser is supposed to support inline HTML, especially including anchor tags.

[LongTengDao]

@cannikin Sorry, I forgot that we now have a website and no longer need to rely on GitHub hack. Just map different translations to each other according to the number of chapters. Is this better? Then just strip the hidden tags I added whether I remove them or not (not only for this case, directly display tag is inherently incorrect markdown rendering behaviour).

[pradyunsg]

If it makes things easier, let's just remove the inline HTML in the cn translation. Once this website goes live, the incentives for folks needing navigation on that document directly, are fairly low.

I'm OK with however we handle this case, as long as the website's output doesn't have raw HTML. ;)

[cannikin]

Okay updated the specs to use numbered section headings for the anchors (#section-1, #section-2) instead of the heading themselves (#strings, #keys). Now when you switch locales it goes right to that same section in the other language! Good idea @LongTengDao !

https://wip--toml-io.netlify.com/v1/en/spec/

[LongTengDao]

Oh, cool when really see it, good job! It was just an idea in the pass time.

Since the content including headings wont be changed in each released version, the hash could be section index + the heading textContent (#1.objectives, #2.table-of-contents, which is more friendly to view), and mapping them between languages by section index only (even translation content changed, section structure wont) internal maybe better. I'm not sure. The present approach is good enough. If there is anything else still need to improve, do them firstly, I'm looking forward to the launch of the website.

BTW: I found links in table of contents are hard coded with #user-content-* even in English edition. After thinking, I think we can remove the TOC section in the website, because we have side menu instead, which is more friendly.

[cannikin]

Question @LongTengDao: we wanted to update the list of locales to include the language IN the languages themselves (similar to how Wikipedia does it). This is what Wikipedia uses, but it lists the country code as "zh":

Should we use that? Is our country code of "cn" correct, or should that also change to "zh"?

[LongTengDao]

@cannikin There are a lot of sub languages under zh, and current version is zh-cn (also zh-hans-cn or cn), so keep cn as short url is correct ;)

While use in ui, 简体中文 is better than 中文, because 中文 is zh, and 简体中文 is zh-cn.

[workingjubilee]

Slightly expanding, to provide a bit more background context: Wikipedia likely uses the ISO 639-1 codes, which are based on the language's own name for itself.
German is Deutsch, which is why the ISO 639-1 code is "de".
Chinese is 中文 (Zhōngwén), which is why the ISO 639-1 code is "zh".

But it's what ISO 639 conceives of as a "macrolanguage", which groups many different languages together, some of which in this case are mutually unintelligible except via the global language of "being really loud, punctuated by throwing things". But there's much fewer variations on the writing system, and the same written text can be understood across the barriers of different spoken languages (at least in common cases), they would just say different things when they read it aloud. So you can expect there might be another translation, but it would follow zh- with something else, and so far there's no 2 letter ISO-639-1 code that uses cn.

[LongTengDao]

@workingjubilee Thanks for expanding.

zh-cn cn are both okay to me, also zh-hans-cn zh-chs... In consideration of there are so many languages alias system, zh-cn maybe not better than short format cn (also not worse).

Just don't use zh, because there could be zh-hk zh-mo zh-tw zh-tw zh-cht, current version is just one of them, which cannot include all of them.

After all, the one-dimensional structure can not fully classify the perceptual language, but will become verbose if it is forced to be rigorous.

Below is just a written pedigree (written language - sub written language - regional terminology habits, I tried to classify them), not involve the subdivision of spoken pronunciation (they are cross sometime...):

• en
  • ... (not the area I'm familiar with)
• zh
  • chs (simplified chinese)
    • cn (here the current version is)
    • sg
  • cht (traditional chinese)
    • hk
    • mo
    • tw

Unless there are conflict between sub alias (zh-cn vs xx-cn, I don't know) -- if that exists, cn will be unusable. Otherwise, they are all okay to me, short better, after all en de jp ko xx-xxx-cn looks a little...

[pradyunsg]

Other than the translation hierarchy, I think we're basically there?

I'll file #??? for discussing the translation hierarchy stuff. Actually, even that seems to have been resolved -- I'll wait for @cannikin to chime in there.

@toml-lang/core What else do we want to do w.r.t. the website? Are we at a point where we can have a PR against this repository for the code that @cannikin has worked on?

[pradyunsg]

@cannikin @mojombo Any updates on the website? I think it'd be nice to have access to the sources powering the WIP website, ideally as a PR against this repository.

[cannikin]

@mojombo was going to take a pass at updating the examples on the homepage.

The code's in the wip branch on this repo, I just opened a PR. When you say "sources" what are you referring to? The sources for the translations? Those are coming from https://github.com/toml-lang/toml/tree/master/versions Any time the site is deployed it'll re-download the versions and build the pages on the site.

The site's live at https://wip--toml-io.netlify.com/

[pradyunsg]

When you say "sources" what are you referring to?

I was referring to the input to netlify -- which as you pointed out, was in the wip branch. Thanks for filing the PR! :D

[mojombo]

I've gone through the homepage and made a few changes. @cannikin did we talk about being able to show previous versions of the spec? I think I said not to bother previously, but actually I think we should. It'll take some time for parsers to come up to 1.0 and people will need a nice way to reference previous versions. Think you could get that working (similar to how we did it with semver)?

[cannikin]

When you switch languages you see only the latest for that language, yeah.

If we're going to show previous versions we should probably do the same thing I did for semver: keep the translated specs in this codebase, including the homepage if someone wants to translate that as well.

[mojombo]

@cannikin In that case, would the website repo become the official source of truth for spec translations? Or how do you see that working?

[cannikin]

@mojombo If it was setup similar to Semver we could use the same website code and logical separation for both semver and toml (and others going forward, like tomdoc):

• The "parent" repo is only the most current, english version of the spec (and CoC, contribution guide, etc): https://github.com/semver/semver
• The website repo contains the site and all translations of the spec: https://github.com/semver/semver.org

What do you think?

[pradyunsg]

I'm on board, for moving all past versions + translations to the toml.io repository.

That'd make the toml repository cleaner and nicer to work in as well.

[pradyunsg]

Our release process will change significantly when we transition to a website, so we probably want to figure those details out before proceeding to publish.

[0az]

@cannikin Some quibbling over pixel-perfect bikeshed placement in the desktop version. Apologies for the low quality image – I think I saved it a few times too many.

TLDR: Margins and horizontal/vertical rhythm.

Other notes:

• The Numbers example block is a bit large. Maybe have it start collapsed, but expand on click? Alternatively, maybe break it up up into int/hex/oct/bin, floats, and inf/nan, or slim it down.
• The spec sidebar's scrollbar extends into the navbar.
• The spec outline might need some sort of hierarchy. The limited hierarchy in the spec is because of the restrictions imposed by using Setext headings, which only allow two levels: three's right out.
• The spec's outline needs some padding at the bottom.

Annotated screenshot of the index page (very tall).

[pradyunsg]

We're live: https://toml.io/. :)