{"action":"created","issue":{"url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/issues/212","repository_url":"https://api.github.com/repos/JuliaDocs/Documenter.jl","labels_url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/issues/212/labels{/name}","comments_url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/issues/212/comments","events_url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/issues/212/events","html_url":"https://github.com/JuliaDocs/Documenter.jl/issues/212","id":172212679,"number":212,"title":"Improvements to the HTML output","user":{"login":"mortenpi","id":147757,"avatar_url":"https://avatars.githubusercontent.com/u/147757?v=3","gravatar_id":"","url":"https://api.github.com/users/mortenpi","html_url":"https://github.com/mortenpi","followers_url":"https://api.github.com/users/mortenpi/followers","following_url":"https://api.github.com/users/mortenpi/following{/other_user}","gists_url":"https://api.github.com/users/mortenpi/gists{/gist_id}","starred_url":"https://api.github.com/users/mortenpi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mortenpi/subscriptions","organizations_url":"https://api.github.com/users/mortenpi/orgs","repos_url":"https://api.github.com/users/mortenpi/repos","events_url":"https://api.github.com/users/mortenpi/events{/privacy}","received_events_url":"https://api.github.com/users/mortenpi/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/labels/Priority:%20High","name":"Priority: High","color":"fd8d3c"},{"url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/labels/Status:%20In%20Progress","name":"Status: In Progress","color":"3690c0"},{"url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/labels/Type:%20Decision","name":"Type: Decision","color":"88419d"},{"url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/labels/Type:%20Enhancement","name":"Type: Enhancement","color":"8c6bb1"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":14,"created_at":"2016-08-19T20:20:43Z","updated_at":"2016-10-02T23:02:42Z","closed_at":null,"body":"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.\r\n\r\n\r\n## Content\r\n\r\n- [ ] **Local vs web builds.** Local docs (e.g. as distributed by system package managers) and web sites (e.g. `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 a `Formats.LocalHTML` to generate sites that are meant to be used locally.\r\n\r\n- [ ] **Clean URLs.** That the page URLs are `latest/page.html` is a bit ugly and we should switch to something like `latest/page` instead. For static sites we can achieve that by having `latest/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 a `serve` function available to locally view the docs.\r\n\r\n- [ ] **Optimize the search.** A bit vague, but both performance and content presentation could be improved. [Blink.jl](https://github.com/JunoLab/Blink.jl) could be an option to run some of the index generation part of the lunrjs while building the docs.\r\n\r\n- [ ] **Multi-version support.** The Julia manual has a widget to switch between versions. I would propose a javascript-based solution, where we'd have a `versions.{xml|json}` in `gh-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.\r\n\r\n- [ ] **Generator information.** We could have have a small footer saying that it is generated by Documenter.jl, when and based on which commit. We should also populate `<meta>` tags with some of this information.\r\n\r\n- [ ] **Extra navigation links.** The logo and title in the navigation menu should probably link to something (docs root perhaps? Logo currently points to the same page, which isn't that helpful). There should be a possibility of having an external link(s) as well (e.g. to GitHub or project website; I would have them separate from the logo/title though).\r\n\r\n- [ ] **GitHub stars.** Like the [MkDocs' Material theme](https://github.com/squidfunk/mkdocs-material).\r\n\r\n- [ ] **Smarter outline.** Determining the document outline (which is used for the sidebar) should be more flexible (#256).\r\n\r\n- [ ] **Make the navigation menu more versatile.** Have a mechanism to filter pages in the navigation menu (#230).\r\n\r\n- [ ] **Additional formats for the logo.** It currently assumes that the file is `logo.png`. We should probably also support additional extensions (`.svg`, `.gif`, `.jpg`, `.jpeg`, `.webp`).\r\n\r\n\r\n## Style and layout\r\n\r\n- [ ] **Mobile UX.** The style should have a responsive design. Currently mobiles also display the desktop layout.\r\n\r\n- [ ] **Next/prev page buttons.** To have buttons (like the current Julia manual), instead of text links.\r\n\r\n- [ ] **Center the `<article>`.** Like the current manual does. Should also probably snap left though, once the width gets large enough.\r\n\r\n- [ ] **Don't lower headers in docstrings.** With HTML we could have normal header tags, and we'd just have to override the style. With HTML5 and since docstrings are wrapped in `<section>` tags, the semantic outline should also be correct.\r\n\r\n- [ ] **Allow blocks in `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: #217.\r\n\r\n- [ ] **Style the quote block.** The `<blockquote>` tag. Currently it is just indented. Probably just add gray background and `border-left`.\r\n\r\n- [ ] **Extend the navigation menu style all the way.** If the page is longer than the navigation menu, the style cut's off. It should extend all the way down.\r\n\r\n- [ ] **Have the navigation menu scroll independently.** E.g. [GitBook](https://www.gitbook.com/about) or [Material MkDocs theme](https://squidfunk.github.io/mkdocs-material/) (#230).\r\n\r\n- [ ] **Collapse navigation sub-menus.** Probably level 3 and deeper should not be displayed by default (#230).\r\n\r\n- [ ] **Handle CDN failures better.** If the CDN serving the fonts or javascript libraries is not reachable, the page rendering blocks until the attempted connection times out (which can take up to a few minutes). This should be handled better, by either a graceful fallback or, alternatively, by bundling all the external dependencies into the HTML build.\r\n\r\n\r\n## HTML-enabled features\r\n\r\nSome larger potential features that are possible thanks to our own HTML output.\r\n\r\n- [ ] **Separate reference manual.** Have function, type, module etc. reference as a separate set of pages, one item per page. Every item would then have a systematic URL (e.g. `/reference/Documents/Page`) to page that would contain the docstring, but also additional information (source links, lists of methods etc). \r\n\r\n- [ ] **Source viewer.** We could distribute the source files as a set of styled and highlighted pages along with the docs. This way there's no need to sync with GitHub etc. for source links and such, and we could even have search working over the source files. Currently the source links can be problematic since they depend on a particular commit etc."},"comment":{"url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/issues/comments/251002360","html_url":"https://github.com/JuliaDocs/Documenter.jl/issues/212#issuecomment-251002360","issue_url":"https://api.github.com/repos/JuliaDocs/Documenter.jl/issues/212","id":251002360,"user":{"login":"mortenpi","id":147757,"avatar_url":"https://avatars.githubusercontent.com/u/147757?v=3","gravatar_id":"","url":"https://api.github.com/users/mortenpi","html_url":"https://github.com/mortenpi","followers_url":"https://api.github.com/users/mortenpi/followers","following_url":"https://api.github.com/users/mortenpi/following{/other_user}","gists_url":"https://api.github.com/users/mortenpi/gists{/gist_id}","starred_url":"https://api.github.com/users/mortenpi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mortenpi/subscriptions","organizations_url":"https://api.github.com/users/mortenpi/orgs","repos_url":"https://api.github.com/users/mortenpi/repos","events_url":"https://api.github.com/users/mortenpi/events{/privacy}","received_events_url":"https://api.github.com/users/mortenpi/received_events","type":"User","site_admin":false},"created_at":"2016-10-02T23:02:42Z","updated_at":"2016-10-02T23:02:42Z","body":"Added to the OP:\r\n> - [ ] **Handle CDN failures better.** If the CDN serving fonts or javascript libraries is not reachable, the page rendering blocks until the attempted connection times out (which can take up to a few minutes). This should be handled better, by either a graceful fallback or, alternatively, by bundling all the external dependencies into the HTML build.\r\n\r\nFor background: yesterday morning (Oct 2) [Font Library](https://fontlibrary.org/), 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."}}
{"actor":{"display_login":"mortenpi"}}