search

tc39 / ecmarkup

An HTML superset/Markdown subset source format for ECMAScript and related specifications
https://tc39.es/ecmarkup/
MIT License
216 stars 62 forks source link

Consider taking care of doctype, <meta charset>, and stylesheet/TOC script for us? #54

Open domenic opened 8 years ago

domenic commented 8 years ago

All of the following seems annoying to have to maintain in my source file:

<!DOCTYPE html>
<meta charset="utf-8">
<script src="https://bterlson.github.io/ecmarkup/ecmarkup.js" defer></script>
<link rel="stylesheet" href="https://bterlson.github.io/ecmarkup/elements.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/solarized_light.min.css">

Should Ecmarkup generate these for me? It already generates <title> I noticed.

I guess it kind of gets away from the custom elements idea. (A custom element could generate the script and link elements, but doctype and meta charset would need to stay.)

bterlson commented 8 years ago

Charset is generated for you. I suppose --css and --js options could reasonably also add includes for the css and js dependencies. Not sure about code highlighting as not everyone needs that dependency... maybe another build option is in order there.

domenic commented 8 years ago

Charset is generated for you.

Oh, it was hiding after the title. Might want to put it before in case the title contains non-ASCII characters.

I suppose --css and --js options could reasonably also add includes for the css and js dependencies.

I kind of just want to use the defaults? It also seems better in that if more people do that it's in more caches.

Not sure about code highlighting as not everyone needs that dependency...

Well again, if it's already in the cache from them viewing any other Ecmarkup spec, it should be fine...

bterlson commented 8 years ago

By defaults do you mean the github.io versions? Having one js and css file on github.io doesn't work well because I can't make breaking changes. We'd need to publish and maintain distinct files for each version. It doesn't seem worth it for optimizing first load of new specs.

domenic commented 8 years ago

I guess that's true. Maybe consider a quick CDN.

bterlson commented 8 years ago

@domenic what do you think about generating relative includes based on the --js and --css options? Ie.

ecmarkup spec.html out.html --css foo.css --js foo.js

would put

<link rel=stylesheet href="./foo.css">
<script src="./foo.js"></script>

in the head. Basically prepend ./ to the argument you pass in on the command line.

The only downside I can think of is if you didn't specify these options you wouldn't get the includes added automatically, which might not make sense if you're rapidly iterating and don't need to keep regenerating the static assets...

domenic commented 8 years ago

Yeah, I mean that seems somewhat reasonable, but for my purposes I don't really find the re-generating static assets workflow to be one I plan on doing. I want to just hotlink to some shared files. I don't claim that's a great idea though.

Also, definitely do <script defer>.

bterlson commented 8 years ago

Considering I don't plan to host versioned assets, what will you do? Just take care to update the "shared file" for each new emu version?

domenic commented 8 years ago

I'll probably just have my specs broken for the short time between new Ecmarkup versions and me upgrading to use those new versions. Like Array.prototype.includes had a bunch of extra whitespace in the sidebar while it was using the hotlinked v2 stylesheet with the v1 output.