Developer discussion on footnotes: implementation and feature behavior

Development
1

footnotes: background on the feature

The best explanation I’ve seen on why-not and what-next for foot notes is Matt’s summary here: Footnote (it’s also the most updated per this recent comment and my forum search)

[The excerpt/read-more feature] simply truncates the post and renders the markdown
on the initial excerpt. To fix [the lack of footnotes], we’ll need to render the markdown based
on the entire post, truncate it at the <!--more--> tag, and make sure the footnotes
option in the writeas/saturday library is enabled.

– Matt, 2019-02

goal: outline detail for development

The goal of this thread is just want to expand[^1] on Matt’s thread - hopefully get Matt’s input - on what exactly is needed, maybe even with code pointers.

As a bonus, since this has been unimplemented so long, it might be helpful to add its status to the end-user documentation (there’s both a howto site and a guides site - not sure which).

details expanded

  • Q1: where does the platform’s markdown logic begin in write.as codebase?

  • Q2: where does the conflicting feature (“excerpt/more”) begin in write.as codebase?

    • A: TBD

  • Q3(TBD): how to handle above-the-fold footnotes.

    I could be mistaken - feel free to correct me. I’m guessing rendering footnotes as-is for excerpt mode would cause link bugs. Seems we’d cause a bug where we’d expose an anchor tag (say from the list view of a blog) with #fn-1, that doesn’t actually have a corresponding destination ont hat page (the list-view of the blog).

    • A1: (guessing this is easier) in the “excerpt” rendering, strip the anchor tag from around the super-script of the footnotes.
      • maybe just render twice instead of truncating?
        This approach makes me think Matt’s initial algorithm outline is maybe not what he’d want to go with (why hackily strip out footnotes when you can just render the post twice: once for truncated view, once for full view - the former with the flag not passed in, the latter where the flag is passed in)
    • A2: (guessing this is harder) in the “excerpt” rendering, transform the href of the anchor tag to be absolute (eg: instead of being a link like #fn-1 it should be https://full-blog.domain/...#fn-1).
      • questionable value.
        Not only is this probably more work, but I’m guessing it’s of minimal value, as following a footnote from excerpt-rendering means you’re not fully engaged in the content yet. so my gut say this isn’t the right choice.

Hopefully this’ll be a helpful post. I’ll come back when I have time. Anyone should feel free to implement though :slight_smile: I’m not claiming I will just yet.

[^1]: I’m thinking if I ran into such clear instructions, I’d maybe just try to implement it real quick and send the pull request. Maybe this thread will move the ball forward one roll, and let someone else do that.

(Discussion moved from writefreely#338)

1 Like
2

Ah, Q2’s answer I think is these two calls to render markdown on lines 51 and 53:

	p.HTMLContent = template.HTML(applyMarkdown([]byte(p.Content), baseURL, cfg))
	if exc := strings.Index(string(p.Content), "<!--more-->"); exc > -1 {
		p.HTMLExcerpt = template.HTML(applyMarkdown([]byte(p.Content[:exc]), baseURL, cfg))
	}

This makes me think Q3’s A1 appraoch is the way to go.

Line 51 (in the blob-specific link I gave) would always take the extension as an argument, and line 53 would never take the extension as an argument.

1 Like
3

Oh, but I guess not passing the extension into the second call wouldn’t render superscript at all, it’d render the raw [^foo] markdown…

… so maybe turning these into absolute links is the way to go? (Q3’s A2 approach)
… or maybe implement a blackfriday feature to make text-only footnote-superscripts (so they render as superscript without the anchor wrapping them)?