feat: single page #1035
feat: single page #1035
Conversation
|
Will there only be the single page mode or both? I really like the multi-page mode, especially if you are editing maths, that's super useful as it doesn't need to render a huge spec. |
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
assets/toc/index.js
Outdated
| * | ||
| * @author Tim Scanlin | ||
| */ | ||
|
|
There was a problem hiding this comment.
@hugomrdias pls add a comment here to note that this is a customised version of tocbot, with bullet points of what changed.
There was a problem hiding this comment.
- removed click event
- made scroll/resize passive events
- cached tocElem querySelector
- made scroll handler debounced instead of throttled
| @@ -2,6 +2,7 @@ | |||
| title: Proof-of-Replication | |||
| bookCollapseSection: true | |||
| weight: 2 | |||
| bookhidden: true | |||
There was a problem hiding this comment.
@hugomrdias mentioned this is hidden as it's org-mode rendering is causing issues and the section is likely to be removed in favour of sdr
go.mod
Outdated
| @@ -3,6 +3,6 @@ module spec | |||
| go 1.14 | |||
|
|
|||
| require ( | |||
| github.com/alex-shpak/hugo-book v0.0.0-20200715185111-e91fa9024b07 // indirect | |||
| github.com/alex-shpak/hugo-book v0.0.0-20200723091818-5eceee52edd0 // indirect | |||
There was a problem hiding this comment.
This came up due to a build failure last week that I think was caused by the same issue I hit today in #1048
| {{- if eq .Level 1 -}} | ||
| {{- $anchor = printf "%s" (delimit $pathParts "$") -}} | ||
| {{- else -}} | ||
| {{- $anchor = printf "%s--%s" (delimit $pathParts "$") .Anchor -}} |
There was a problem hiding this comment.
We can simplify this and change the delimeter... ideally we'd match the old anchors
There was a problem hiding this comment.
@hugomrdias mentioned, this is also the line we need to handle the anchor rewrite
There was a problem hiding this comment.
here we also need to handle the case of a file named index.md using the same behavior as _index.md
…into feat/single-page * 'feat/single-page' of github.com:filecoin-project/specs: feat: spec state badges (#1036)
- fix header status badges
|
I've fixed the header rendering hook so that each h1-h6 element is rendered inside it's own header element which can contain other content, such as spec-section-status badges, without those appearing in the content, and brought the branch up to date with beta. It's all looking pretty nice now: https://bafybeif2nshn25cowmv64rchk2h2eyw4cccwd7nfhibpklxranc43ijlt4.ipfs.dweb.link/ The content of the heading elements is used to create the Toc, so including anything other than the heading in them is troublesome, as it will appear in the ToC. Pulling them out of the heading element fixes that, but then breaks the numbering, as that is done via CSS counters, which were assuming the heading elements would all be direct children of the body. That's fixed with a CSS tweek. Alas now we hit a similar problem with math/katex support... We can't run katex on the entire document; in single page mode, it is way too big. So we need to wrap the sections that use katex in an element so we can reduce the scope, but that again will break section numbering. Hopefully that can be fixed with moar css. Both the ToC creation and the math mode processing should ideally be pulled to a build time rather than run time step. |
|
I'd like to mention that build-time KaTex is possible with a fork of Hugo (it's really a small patch), the details are outlined in this Blog. Sadly this patch won't be applied upstream as it's using CGo. So if someone would write a version of goldmark-qjs-katex that is using a JS implementation that runs in pure Go (like e.g. goja, it might be able to be upstreamed into Hugo. If it would be me, I'd just use the fork mentioned above for now and explore future improvements on it when it turns out it's not a viable solution in the long run. |
|
@vmx i was initially strongly against relying on a forked hugo... i have it working with client side rendering, but the more I think about it, the more I think you are right... I should stop fighting hugo and start forking it instead. We don't need to keep up with changes in hugo, we just need a stable platform that works for the content we have. Beyond math content, the current ToC situation is particularly egrigious, as hugo has the data on in page headings, but only exposes it as pre-formated html ToC that we can't re-use to build our the all-pages mega ToC. If we fork hugo we could expose the page level headings as data and template the ToC we need at build time. I shall explore. |
ensure all the js that is needed is bundled and initalised in an orderly manner. previously, shortcodes would include script elements to a remote cdn which can lead to many copies of the same lib being requested in single page mode. License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
|
Single page, Links, ToC, and math-mode are all working in this PR, but the heading numbering remains fragile. The current solution uses heading-hooks to catch in-page sub-headings, and update their id, and format them with a status badge etc... alas that heading-hook feature is provided by the goldmark markdown parser, so org-mode docs do not trigger it, and have incorrect headers, and are currently missed in the section numbering scheme... which leads to subsequent section numbers not matching between the ToC and the actual headings... (of note, the same problem exits in the old version of site) I am looking into solutions. |
css counters are scoped to the element that first declares them. This change declares the counters at the content root, so that heading elements share them regardless of nesting. This also means that we have to clear out all the lower order counters for every header as they are shared. License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
|
I have
My biggest concern with this branch right now is the perf and UX of the ToC which I will look at today. The "follow on scroll" makes it feel jumpy when clicking between sections, and the initial render is slower than I'd like. There is also the issue of whether building the ToC client side is an acceptable solution. Cons |
|
Just so we are all on the same page, the original spec site relied on authors to add front-matter at every level in the doc to describe the ToC headings that should be build, duplicating the heading structure in the document. It was a manual process that would get out of sync, and leave the ToC and the content not matching up e.g.
The manual nature of it was pleasingly simple, but there are now several examples across the original site where the ToC and the content do not match. This branch does not attempt to get hugo to build a ToC for the single page view. In page JS grabs all the headings from the content and builds the ToC on the client, so it's always includes the same items. There is no functionality in hugo to get all the headings from all the pages in a way that lets you build a ToC. Am on the look out for a neat hack or workaround that will let us do it. However while the section numbering is handled by CSS it does not gurantee that the numbers will always match up. If we jump from an h1 to an h3 in a markdown document, with no intermediate h2, the content will correctly number these sections as while the ToC will number them arguably, this is an error with the content that should be fixed, but I just want to highlight the fragility of using css to handle the numbering. That said, it is a lot more stable / consistent in this branch. |
re-use the portable link template :woo hoo: License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
or it should get its own doc License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
|
org-mode sections remain a problem. In the original site it looks like we were using ox-hugo to transform the org-mode docs into markdown before letting hugo parse them. Right now we are leaning on hugo's built in support, which means fewer deps, which is nice for authors, but it also doesn't work with our heading re-writing, so if we are goinng to add more org-mode docs in the future we need to find another solution, which is probably switching back to using ox-hugo to pre-process them. |
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
|
@olizilla these are really great achievements and I think that the pros outweigh the cons. Having katex rendering scoped is also very reasonable, given a minority of sections need it. I have found a bug in the numbering. It seems that subsections and subsubsections counters do not reset on section start. So, if section 1 goes up to 1.6.9, then section 2 starts from 2.7.10 - see screenshots below.
|
|
@yiannisbot yep that is an known issue, it affects Chrome, but not Firefox. Good spot though, remain vigilant. ✊ |
This is a loving homage to the original ToC. It brings back all the old behaviours and great perf. TocBot perf is terrible on a large doc, so it is removed, in favour of the old ways. Fixes up resource loading, notably defering katex till well after the page is loaded, to speed up ToC build and reduce the time to get to a useable document. License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
numerous content heading fixes License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
- fix toc and content numbering stability - remove header element that wraps headings to avoid issue with org-mode docs not getting headers re-written - fix missing section headers in content that ment the listings and appendix were missing - fix nesting of glossary headings License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
now i'm tweaking the in page fragment links to match the old ones where possible and tracking down some broken links
|
|
Broken links are fixed, now verifying and simplifying the logic that maps the headers and links. |
- match the old spec for generating heading ids and linking to them - fix issues with old content missing h1 elements. - document what is going on in render-heading and render-link so others may suffer less. License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
|
Just so its on the permenant record: From adopting and working on this PR, I still dont think it is in our best interests to coerce hugo to build out a single page website, but in the sprit of "agree and commit" hugomrdias and I have got it working. It re-introduces some complexity that we don't have in the multi-page site (e.g custom id generation, header re-writing, link re-writing). We are working against the grain of what hugo is designed for. Long term, we will get better results on this project if we make the specs site be multi-page, or use a tool that is designed building out single page spec sites e.g. remark.js or bikeshed or similar. Regardless, this PR re-introduces single page mode, and has far fewer inconsistencies than the original spec site. |
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
License: MIT Signed-off-by: Oli Evans <oli@tableflip.io>
|
@hugomrdias pls review this when you get back. The old CSS needs cleaning up, as do a lot of the old templates. It's now very hard to justify using the book hugo theme, as we have to override in both templates and css. The code would be simpler if we just started from scratch. On which, the perf of TocBot was terrible, and I couldn't face hacking it better, when we also had the request to re-integrate the toc slider, so I wrote a relatively simple and quick toc-builder and ported the toc collapsing logic from the original spec site, so it now feels much more similiar to the orignal site, and the ToC doesn't grind to a halt while it tries sets up hundreds of click handlers and scroll watchers. Would be worth reviewing those parts at least. |
TODO: