Proposals: deep links and block embeds

docs/proposal-block-embeds.md

@@ -0,0 +1,29 @@
+# Proposal: Block Embeds
+
+Embedding content blocks (sections, or any html blocks with id) so that they are visible in the document where they are being linked from.
+
+We could use [VS Code Peek Definition](https://docs.microsoft.com/en-us/visualstudio/ide/how-to-view-and-edit-code-by-using-peek-definition-alt-plus-f12?view=vs-2019) to do this.
+
+You should be able to embed any wiki link, using the same [[proposal-deep-links]] anchor syntax:
+```
+page#anchor
+```
+
+Our options for syntax:
+
+1. HTML style embed
+<embed ref="blank-document#section-3-bis"/>
+
+2. Mediawiki hybrid monster
+[[blank-document#section-1]]<embed />
+
+3. Our own special ?embed hack
+[[blank-document?embed#section-1]]
+
+In order to get these to render inside HTML pages, we will need to customise the renderer. [MDX](https://github.com/mdx-js/mdx)
+
+Before properly implementing embedding with custom sections we need to solve some of the issues described in [[proposal-deep-links]]
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[proposal-deep-links]: proposal-deep-links "Proposal: Deep links"
+[//end]: # "Autogenerated link references"

docs/proposal-deep-links.md

@@ -0,0 +1,86 @@
+# Proposal: Deep links
+
+Linking to a section within a document.
+
+A section is a part of a markdown document.
+Sections are automatically created when using a heading.
+
+Custom sections can also be created by using content blocks (see [Declaring content blocks](#declaring-content-blocks) and [Content block](#content-block])
+
+
+## Section Heading
+
+Step 1: Just link to headings:
+
+[[document#section-heading]]
+
+## Declaring content blocks
+
+Step 2: Declare sections via HTML content blocks
+
+`<div id='content-block'>`
+<div id='content-block'>
+This is a content block that has been defined using html, instead of automatically generated by a heading.
+</div>
+`</div>`
+
+This will automatically work because element ids are anchor targets in HTML:
+
+[[document#content-block]]
+
+You can use this for any HTML element (as long as it doesn't get filtered out by e.g. GitHub)
+
+### Challenges
+
+There is a problem with html blocks in md. The content of the block is not rendered as markdown but as html. Unclear how this is accounted for in the [MediaLink](https://www.mediawiki.org/wiki/Help:Links) reference.
+
+> Note that this is only relevant in the context of embedding because when navigating we only care about the beginning of the section.
+
+An alternative for this would be to use self-closing html tags and just assume that a section runs into the beginning of the next block boundary, defined by another HTML element or a section heading, or end of file:
+
+```
+<div id="content-block" />
+```
+
+
+## Declaring inline content blocks
+
+Step 3: Use span instead of using a block element (div)
+
+- Outline <span id="1" />
+- Inline text <span id="2" />
+
+This does not have the problem with markdown not being treated as markdown inside html blocks, because there is no content in the html blocks.
+
+## Syntax sugar for blocks
+
+Step 4: Syntax sugar (in the future)
+
+```md
+- Some ideas. Explore at a future
+  - Many bullets #a
+  - Ideas here [#b]
+  - Then some [^c]
+```
+
+## Alternatives:
+
+We could use reference blocks:
+
+[foam:block]: id
+
+[foam:block]: end
+
+```
+[foam:block]: id
+
+Hello
+
+[foam:block]: end
+```
+
+Challenge here is that we need to have a blank line immediately before each link reference definition.
+
+The `foam:` namespacing is just to ensure we don't collide over any real documents, e.g. one called "block.md"
+
+End of block is optional, and section can run until the next heading