[Discussion]: Implementing Footnotes in DocC

Development Swift-DocC
1

Hi everyone,

In this thread I want to further discuss the implementation footnotes based on this proposal.

The implementation consists of three parts (or four): Swift-Markdown, Swift-DocC and Swift-DocC-Render.

Swift-Markdown

With the help of @QuietMisdreavus we have enabled the parsing of footnotes in Swift-Markdown. Some changes to the swift-cmark library were necessary to make this possible (the fourth part).
It consists of two elements, the inline footnoteReference and the block footnoteDefinition. Both have a footnoteID as data and footnoteDefinition can contain child elements.

Swift-DocC

This is the part where I am stuck because I do not really understand what is going on. I have added some RenderNodes but these seem to do very little.
My idea is to not change too much about the sturcture, so no grouping of footnotes or anything, just put in in the main content and leave it up to Swift-DocC-Render.

// footnoteReference
{"type":"paragraph", "inlineContent": [
  {"type": "text", "text": "a footnote:"},
  {"type": "footnoteReference", "footnoteID": "1"}
]}

// footnoteDefinition
{"type":"footnoteDefinition", "footnoteID": "1", "content": [
  {"type":"paragraph", "inlineContent": [
    {"type": "text", "text": "An explanation of the footnote"},
  ]},
  {"type":"paragraph", "inlineContent": [
    {"type": "text", "text": "A second paragraph"},
  ]},
]}

Swift-DocC-Render

I haven't started yet on this part. Basically two new components will need to be added, the footnoteReference with id="[footnoteID]-ref" and ref="[footnoteID]-def" and vice versa for the footnoteDefinition.
The footnoteDefinitions, if there are any, need to be rendered at the bottom of the main body, before a possible See Also section.

More difficult will be the implementation of the mobile friendly footnote, as described in this reply on the pitch.
We will need to create some kind of pop up for small screens but not for wide screens.

I have zero experience in Vue.js so any help for this part is very welcome!

Closing remarks

I am doing this as part of a thesis (, for which the deadline is this friday ◑.◑,) so my focus right now is to just get a working prototype on a seperate branch as fast as possible but of course this needs to be properly implemented and documented afterwards.
I think the implementation I propose should not introduce any breaking changes to existing documentation projects.

Questions

Specific questions I have are:

  • Which classes need to be added or changed in Swift-DocC in order to use parse the footnotes with Swift-Markdown and put them in the Render JSON?
  • If we make two components in DocC-Render which component should be delegating the work to render them?

Thank you for your time, help and answers!

2

I think the best answer to this will likely depend on the Render JSON schema changes that come out of this.

For example, if the footnotes section ends up being a generic mapping to markdown syntax that can be used where any other markdown block can be used and rendered, then the ContentNode component from DocC-Render will likely be the most appropriate place since that is mostly what it is intended for.

However, there could be other places that make more sense if the JSON is structured in a more explicit way—it's hard to say exactly without first having an idea of what the data might look like.

1 Like
3

There is a GenericModal component in DocC-Render that might be helpful for this kind of UX, although it also might not be an exact fit for this particular scenario.

1 Like