filecoin-project
Using weight to determine document order is awkward to reason about
We are using weight: <integer> in yaml front matter to determin what order to concatenate markdown files together for any given section.
To change the position of a document you have to edit the weight value of all the affected docs. Given:
alpha.md - weight: 1
beta.md - weight: 2
gamma.md - weight: 3
If i want to move gamma.md to be first, i have to edit the weights of all the other documents. It's a friction that means we avoid significant reorganisation of content even if it would be beneficial.
An author would also have to check the weights of all the other documents in the section to figure out the context of what content comes before or after the file they are editing, or rely on the generated site.
To some extent we have premauturely split markdown files into many small chunks, so some of this issue can be reliveed by merging several small documents into 1. But for larger documents something like a markdown imports function as offered by Spec Markdown (https://spec-md.com/#sec-Imports) would be easier to reason about, where by a link that targets a markdown file gets inlined as part of the rendering process. That way the ordering is managed by the document order and so to editing the order feels natural, you just move the import, and authors can see what file will come before and after the one they are editing.
intro/_index.md
# Welcome to the thing
some intro and many subheadings
[](./next-big-chunk.md)
[](./other-chunk.md)
[](./in-summation.md)
