search

toml-lang / toml.io

Source Code for toml.io
https://toml.io
MIT License
42 stars 44 forks source link

Allow downloading specs in plain text #11

Closed ChristianSi closed 4 years ago

ChristianSi commented 4 years ago

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.

eksortso commented 4 years ago

Is there a use case requiring a text version of the spec that couldn't be addressed by linking to the version on toml-lang/toml?

pradyunsg commented 4 years ago

@eksortso There's no sources over on toml-lang/toml anymore -- it's all in this repository.

I do think a much better way than providing the .md files on the domain would be to add a link like "See sources" linking back to https://github.com/toml-lang/toml.io/blob/master/specs/en/v1.0.0-rc.1.md (and likewise for others).

ChristianSi commented 4 years ago

@pradyunsg Sure, a link to this repo is fine – just as long as they are easily discoverable. (I would not have known that the files can now be found here; all I knew was that they are no longer in the main repo.)

cannikin commented 4 years ago

How prominent would you expect this link to be? At the top of the spec? At the bottom? A major callout, like a button, or would a text link be sufficient?

eksortso commented 4 years ago

@cannikin As it turns out, it would need to be as prominent as a historical archive ought to be. I wasn't thinking in those terms before, but I am now.

@ChristianSi A link to the "Source" in the top bar ought to suffice. Anyone can look for "source" on the page to discover it. For other languages, similar terms can be used. I'd say it ought to be as prominent as the GitHub logo linking to the toml repo currently is.

@pradyunsg It's probably important that perma-links to those docs don't reference blobs directly. It's an aesthetic choice, but I'd be more comfortable finding these things at predictable URLs.

ChristianSi commented 4 years ago

@cannikin, @eksortso: Text link would be fine with me. Top or bottom I don't care, as long it's findable.

pradyunsg commented 4 years ago

It's probably important that perma-links to those docs don't reference blobs directly. It's an aesthetic choice, but I'd be more comfortable finding these things at predictable URLs.

Well, linking to master is certainly a stable URL.

cannikin commented 4 years ago

Well, linking to master is certainly a stable URL.

There's a movement right now to rename master to main, we just did this in RedwoodJS.

I was going to link to the raw content: https://raw.githubusercontent.com/toml-lang/toml.io/master/specs/en/v1.0.0-rc.1.md (also contains master in the URL).

pradyunsg commented 4 years ago

I'm 100% OK to do so here if folks feels strongly about it either way, but I don't think renaming of the base branch is something that happens super often. :)

I'd still consider whatever branch name we end up using to be something that stays for a long time.

eksortso commented 4 years ago

If we're going to rename the branches, it's now or never.

cannikin commented 4 years ago

Rename complete! Future PRs will be against main and Netlify deploys main as well.

cannikin commented 4 years ago

Okay take a look here: https://deploy-preview-13--toml-io.netlify.app/en/v1.0.0-rc.1

This is added at build time and so isn't translated. The easy way to do that is to just add the link in each individual spec and it'll just be added like any other text link when the markdown is converted. If that's the case I'll roll this back and I can add the links to the english specs. We can open issues to add the link to the other languages.