Typical use cases will break these API docs

[nilslindemann]

trafficstars

Edit 2018-11-9: This is tldr, i shortened it.

1: When users disable Javascript it results in a white page.

2: Archiving this on archive.org results in 404 pages.

3: Tweaking these docs with userscripts can break the links on the right. Example Greasemonkey Script. Test it on https://package.elm-lang.org/packages/elm/core/latest/Basics. You may have to reload the page.

// ==UserScript==
// @name         Fold the API Elements for better overview.
// @match        https://package.elm-lang.org/packages/elm/*
// @require      https://code.jquery.com/jquery-3.3.1.min.js
// ==/UserScript==


(function() {
    'use strict';
    setTimeout(function(){
        $.noConflict(); // https://api.jquery.com/jQuery.noConflict/
        jQuery(document).ready(function($) { // https://api.jquery.com/ready/
            $($('html > head')[0]).append(
                '<style type="text/css">' +
                '.center {width:auto;margin-left: 2em;margin-right:18em;}' +
                'body > .center {min-height:100vh!important;}' +
                '.pkg-nav {position:absolute;right:1em;}' +
                '.block-list {width:auto;}' +
                '.docs-block.folded {display: inline-block; border: 1px solid #eeeeee; margin: 0 10px 6px 0; overflow:auto;}' +
                '.docs-block.folded > .docs-comment {display: none;}' +
                '.docs-block.folded > .docs-header {padding: 10px;z-index:1!important;}' +
                '.docs-block.folded > .docs-header div * {display: none;}' +
                '.docs-block.folded > .docs-header div {font-size: 0;}' +
                '.docs-block.folded > .docs-header div a[style="font-weight: bold;"] {display: inline-block; font-size:16px;z-index:0!important;pointer-events: none;}' +
                '.docs-block.folded + .docs-block.unfolded {border-top: 0;}' +
                '.docs-block > .docs-header {cursor:pointer;}' +
                '.docs-block.folded + docs-block.unfolded {border:0; margin:0; padding:0;}' +
                '.docs-block.unfolded {border:0; padding-top:1em;}' +
                '</style>'
            );
            $('.block-list .markdown-block').remove();
            let blocks = $('.docs-block');
            blocks.each(function(){
                $(this).addClass('folded');
            });
            let headers = blocks.children('.docs-header');
            headers.on('click', function(e){
                e.preventDefault();
                e.stopPropagation();
                let folded = $(e.target).closest('.docs-block');
                if (folded.hasClass('folded')) {
                    folded.removeClass('folded');
                    folded.addClass('unfolded');
                } else {
                    folded.removeClass('unfolded');
                    folded.addClass('folded');
                }
            });
            /*$('a').on('click',function(e){
                window.open($(e.target).attr('href'),'_self',false);
            });*/
        });
    }, 1000);
})();

You can uncomment the $('a').on('click' ... code to enforce the reloading of the page but then, whats the point of using a single page app? Further, it will spam the browser console with error messages until the new page loads.

The single page app approach is wrong here. Make these docs be semantic HTML (see #289), sugared with unobtrusive Javascript: First create a version which is usable with CSS and Javascript disabled. Then enable CSS and make this work as expected too. Then add everything else missing, using unobtrusive Javascript.