toml-lang/toml.io

Source Code for toml.io

toml.io

The public facing site at https://toml.io

Contributing

• Copy spec/en to create new locale directory
• Update _locale.md with the name of the language in its own alphabet
• Translate index.html if you want
• Create a version in the form of v1.0.0.md

toml.io's Issues

Internal links (crossrefs) in specs are broken

When I click on https://toml.io/en/v1.0.0 on any of the internal links, e.g. in the list of types following "Values must have one of the following types", nothing happens because the link is broken. The problem is that these internal links are tailored for GitHub, but on toml.io the files are rendered in a different way and so the links don't work. For example, "String" is a broken link to https://toml.io/en/v1.0.0#user-content-string, while the correct link would be https://toml.io/en/v1.0.0#string.

toml.io must adjust these internal links when rending the files, to make them work.

Navbar and body links are different

In the page for the 1.0.0.-rc.1 version (https://toml.io/en/v1.0.0-rc.1), under 'Key-Value pair', the links to the types (like string, integer, etc) do not lead to the corresponding content.

But the links in the navigation pane on the left leads to the content.

The hrefs in the links of navigation pane have 'section-' in them and the links under 'Key-Value pair' has 'user-content-'.

And which static site generator is used for the website?

Syntax highlighting sees "fi" as a number

This is due to a mistake in this regex:

/([\+\-\d(inf|nan|0o|0b|0x)])+[\d_eETZa-fA-F\:\-\+\.(inf|nan)]+/

( within character classes doesn't indicate a group.

Internal links are broken

On toml.io/en/v1.0.0-rc.3, go to, say, the part that says "Naming rules for tables are the same as for keys (see definition of Keys above)." The Keys is a link that is supposed to link to the Keys section. However, it does not. It links to https://toml.io/en/v1.0.0-rc.3#user-content-keys but that doesn't go anywhere. It should link to https://toml.io/en/v1.0.0-rc.3#keys.

I don't know how this web stack works at all so I figured I would make an issue rather than try to fix it myself. It's very weird that the table of contents uses links that end with (for example) #user-content-keys and it works perfectly fine, but using that outside of the ToC is clearly not working.

Explore adding an FAQ section

This has come up in multiple discussions over on toml-lang/toml, as a suggestion; for placing things that do not belong in the specification itself.

Make toml.io!

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/

Doubt: Space within the table key

I had a doubt. Wasn't sure which would be the right place to ask.

From the website, I see that.

[ g . h . i ] is same as [g.h.i].

But how will

[ g h . i ] be parsed.

Will g h be considered as the first part of the key (not sure if I'm using the right terms (-: )?

Or is it an error?

And in table arrays, are white spaces allowed between the double braces. Is something like [ [ product]] valid?

Clarification on normalizing newlines in a string literal

The toml language states:

TOML parsers should feel free to normalize newline to whatever makes sense for their platform.

I am not sure how to interpret "should feel free". Is it obligatory to interpret the newline according to what platform the parser is running on, or is it allowed to be parser-dependent on how to interpret newlines in a stirng literal?

Add an issue template

Basically a file with a better phrasing of:

Please file issues and questions related to the TOML specification at [link]. This repository/issue tracker is only for the toml.io website and not for the language specification.

Originally posted by @pradyunsg in #16 (comment)

Allow downloading specs in plain text

While the syntax highlighting of toml.io is very nice, for some use cases access to the raw Markdown files is more convenient – saw when comparing different released versions (diff). One possibility would be to complement https://toml.io/en/v0.5.0
with a plain text file accessible under e.g. https://toml.io/en/v0.5.0.md – and likewise for all other released versions. Then add a link "Plain text version" to the rendered HTML version to make the other version discoverable.

Add contributing / maintainance documentation

Context: #8 (comment)

Where does the supporting ANBF go?

The TOML .md file also has a supporting .abnf file which together serve as the overall specification.

Right now, I don't think we have the .abnf file in any specific location in this repository. @cannikin Any suggestions on how/where to put this on the website + this repository?

Mixed-type arrays are still invalid, aren't they?

The example at the top of the page has the following two lines:

[clients]
data = [ ["delta", "phi"], 3.14159 ]

The problem is the value of data. which is a mixed-type array, which is invalid in TOML v0.5.0. Although there's an open issue regarding whether mixed-type arrays ought to be allowed, that issue is tagged post-1.0.

So assuming the issue isn't pressed before v1.0.0, do you think we need to remove or replace the mixed-type array from the lead example?

Add release dates to files

Nowhere in the different versions of the spec published on toml.io it's visible at which date that version was tagged and published. To document TOML's history, it would be good a show a little note "Published on xx April 2020" somewhere at the top or bottom of each version of the spec.

I guess we're making a semi-blessed JS TOML parser for the website!

Following up on this:

@workingjubilee Yes please! haha I hadn't figured out how to actually do that yet, but I found this site: https://toolkit.site/format.html so I knew it was possible.

@mojombo had a good point that some types aren't directly translatable, like native datetimes. What do we do in those cases? Maybe just output a string version of the datetime? Or replace the content with a comment (even though it isn't technically legal in JSON)? Likewise do you take a datetime string in JSON and try and covert it to native datetime for TOML?

Originally posted by @cannikin in #1 (comment)

We can do "lossy data, but structural match" or "lossy structure, but data match" translation across JSON : TOML, the data-lossless one involving type annotations embedded in the JSON structure. By default, we can favor the first, cleanest translation (where JSON and TOML are 1 to 1), but when the translation would involve loss of type data like that, we can display an error state or perhaps a "warning state" I guess and point the user to an option to enable alternative translations. After all, we already have to intelligently handle JSON literals ("Uh, Ma'am, this is a hash table").

I think recognizing JSON strings that are exact matches for the subsets of the RFC3339 format that TOML supports and casting them to TOML datetimes is a sane default, because it's lossless as a result, but not if they are off by even a single whitespace(!), and that a similar logic of Maximal Strictness would serve well on all type casts. No guessing and no magic, really, just return to user and comment on the results, maybe offer choices if we can. And I think that's going to be easiest.
Edited: I'm so sorry, I was mid-way through my coffee when I first posted this.

MayThu

Note
This repository is for the toml.io website only. If you have a suggestion for the TOML spec itself, head over to https://github.com/toml-lang/toml and open an issue there.

LICENSE file

I think there would better be a LICENSE file same with toml-lang/toml, at least in specs folder. If not, no one can use the whole translation docs in the futhur, because the default copyright belongs to all translators self.

Specification breaks at certain window widths/zoom levels

For example at 140% I get a horizontal scrollbar:

Which gets even worse if you click a menu item, because it scrolls to the right:

At ~160% the mobile nav kicks in.

The exact values differ a bit per system, depending on screen resolution, window size, screen scaling, etc. You can also reproduce it by just making the window smaller, but the main gist is: there are some width that don't work well.

It should really just make the main content smaller; the reason it doesn't is because some wide pre tags make it larger. pre { max-width: calc(100vw - 21rem); } fixes it, but there's probably a better way.

Changing the language picker should take you to index.html if translated, but doesn't

Right now, even if index.html is translated, changing language will take you to the latest version of the spec. It should take you to the translated index.html:

Steps to Reproduce

1. Choose 简体中文 as your language
2. Page redirects to https://deploy-preview-34--toml-io.netlify.app/cn/v1.0.0

Expected Behavior

Should redirect to https://deploy-preview-34--toml-io.netlify.app/cn/