search

n8willis / opentype-shaping-documents

Documentation of OpenType shaping behavior
161 stars 15 forks source link

HTML output #149

Open n8willis opened 1 year ago

n8willis commented 1 year ago

Somewhat in conjunction with #148, it'd be good to consider an output for the docs beyond "it's a GitHub project" live site-formatting. With the goal that the material can be used on its own.

Perhaps the easy solution would be to include some CSS or other templating material for a/some popular Markdown-to-HTML converters.

No strong preference myself; the obvious first choice might be something common like Pandoc, styled to resemble the pages as they appear here in their current, online form. Or maybe to mimic the formatting of general "Github Pages" output.

But if there are special requests or other targets where it would make sense to fit in with related material (e.g., similar in format to Unicode or MS/Apple OpenType docs -- as far as general typographic hierarchy and nav is concerned, not branding or style details, obviously) there's no reason not to look at options for that, too.

n8willis commented 1 year ago

There is now an attempt at this underway in #154, for those currently on the edge of their HTML seats.

n8willis commented 1 year ago

Pinning this issue now because I believe the HTML PR is workable enough that it really needs feedback from outside.

No detail is too small.

n8willis commented 1 year ago

I've merged in the HTML output system via #154 .

Moving forward, any formatting issues that readers encounter which are related to GitHub's built-in "repo view" rendering of the docs are still welcome, but the HTML output version is to be regarded as primary. So if there's ever a conflict between them, getting the HTML to look good wins out.

In some ways this is a rather big change, but it's not content-related and I don't think anyone had issues since it was in WIP mode for several months. I just had to get it done so that I can (potentially) push out a couple of other changes to the image system.

I will see about also bundling up an "asset set" zip/tar bundle for people who don't want to mess with Sphinx. That depends on whether I can finesse doing it without the license being finalized, since I expect a downloadable bundle to get a lot of traffic that wouldn't care about building it from scratch.