-
Notifications
You must be signed in to change notification settings - Fork 480
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Meta: improvements to the HTML output #212
Comments
Good list, thanks for writing it up. I'm fine with all the items listed apart from the clean URLs one. I've never really understood why hiding the
That's a lot of separate pages for |
Just about to kick the tires here. In contrast with what's stated here, there doesn't appear to be a |
Added an entry to the OP.
|
Nice list. By the way, have you seen this? It might make the whole job of setting up docs on GitHub even easier, if everything can stay on master. |
Just tried this out - it's fairly awesome! Congrats! The first thing I noticed - the lines of the HTML are very long — typically up to 5000 characters or more. It doesn't cause any problems, but you could probably put returns after |
The trouble with using GitHub's new
To look at the generated content I'd suggest just using the browser's "inspect" feature ("Inspect" in Chrome, and "Inspect Element" in Firefox) which formats the HTML nicely. |
I actually like clean URLs, so a +1 from me for that feature. |
|
On the extra navigation links: I think it would be really good if we could add a link back to the repo for the project somewhere. That seems to be one of the major navigations I use: go to the doc, browse around and then I want to go back to the project github page with one click. I could click back a lot, but would much prefer a direct link. |
Double backticks denote LaTeX in Julia's Markdown. Inline code should be surrounded by single backticks, and should be styled correctly. More accurately I think it was odd number of backticks for code, even number for equations/LaTeX. |
Ha, I didn't know about that, but this solves this completely, thanks! |
(FWIW there's a recent addition to the Julia docs that outlines all the markdown syntax that we currently support http://docs.julialang.org/en/latest/manual/documentation/#markdown-syntax.) |
It would also be nice to add an option to include the number of stars on github under the logo like in the Mkdocs Material theme |
Added to the OP:
For background: yesterday morning (Oct 2) Font Library, where we get the Fantasque Sans Mono font from, went down for half a day, making all of the HTML builds unusable for that period. |
Probably the most pressing feature on this list is a button to navigate to root page of the associated github repo. I currently always click "edit on github" and then navigate to the project root. |
Looking at the screenshot below which is from chromium on linux: In my opinion the distance between the bullets on the right is a bit large. Also, the style of the version selector feels a bit off (the current one gives me a Windows 98 vibe). It also feels a bit too close to the search box making it looked a bit cramped. Just a few personal opinions :) |
The dropdown is should just be the default system one. Doesn't look a bit odd in chromium though. Tweaks to the css are most welcome, I'll get around to sorting them at some point, unless someone else beats me to it. |
Mobile UX seems important especially since the Julia manual has been ported to Documenter. |
Another thing, when you click on a menu entry the menu get scrolled to the top. Is this a browser thing or is it possible to keep the position of the left menu and just refresh the right section. In documentations with a lot of menu entries (like the julia manual) it is a bit annoying to get taken to the top all the time. |
It would be nice if the buttons/links could have Then again, hardly anyone seems to use this anymore, apparently Google stopped using it for indexing at some point... |
Various issues and thoughts that should or could be addressed that are related to the HTML output. Some of these might deserve a separate issue to actually decide the details. We could also add additional things here as they come up, so this could serve as a meta-issue.
Content
gh-pages
) have different requirements, e.g. URL schemes, same-origin policy, bundled scripts and styles (local sites should probably work offline). Instead of trying to accommodate both in the same output, we could just have aFormats.LocalHTML
to generate sites that are meant to be used locally.latest/page.html
is a bit ugly and we should switch to something likelatest/page
instead. For static sites we can achieve that by havinglatest/page/index.html
(like MkDocs does). This won't work that well for local build though, so we'd need to split them up and have aserve
function available to locally view the docs. (Allow using pretty URLs #485)versions.{xml|json}
ingh-pages
top-level that gets updated on every deployment and contains a list of versions available. Then a small script would read that and display a small widget. Should be javascript based, so that you wouldn't have to update all the versions every time a new tag gets released etc. (Translated and Other Version Docs #297, Add version selector dropdown menu #358)<meta>
tags with some of this information.logo.png
. We should probably also support additional extensions (.svg
,.gif
,.jpg
,.jpeg
,.webp
). (Update HTMLWriter logo handling and arguments #953)Style and layout
<article>
. Like the current manual does. Should also probably snap left though, once the width gets large enough.<section>
tags, the semantic outline should also be correct.Footnote
s. Currently the HTML output assumes that footnote contents should all be inline, but it should actually support block level content as well. Ref: Update HTML docs #217.<blockquote>
tag. Currently it is just indented. Probably just add gray background andborder-left
.hide
feature in Add an option to hide pages in sidebar #282).HTML-enabled features
Some larger potential features that are possible thanks to our own HTML output.
/reference/Documents/Page
) to page that would contain the docstring, but also additional information (source links, lists of methods etc).The text was updated successfully, but these errors were encountered: