Responsive images and markdown

Wed Mar 27 19:07:27 EDT 2019

Sherwood, great question and well laid out. If a good solution comes up I'll probably want it as well.

My idea is to _post-process_ the HTML output to convert marked data into a picture element, rather than to construct a picture up front that can withstand parsing from Markdown into HTML. In the source text, I suggest cramming the image's source data into the image's title attribute, which then gets unpacked in the post-processing.

I wrote the following as I was working out the idea.

---

I haven't become familiar with the `<picture>` element but I get the idea from what you've presented. As for the CSS presentation, fancier things are of course possible but that doesn't change the need for well-structured content and good markup.

Like you, I've got no Javascript background, and I'm happy enough to keep it that way. In fact I'm not much of a programmer at all, which may be an advantage as I try to always empathize with the non-technical writers and readers.

So I'm looking at the data salad that supports 'picture' and thinking it hardly fits into standard prose, and I think one way to come at it is, firstly, to pick the appropriate existing Markdown that will tuck the structured data into a place it would pose no harm if visible to readers, and, secondly, to write a script that will _post-process_ the HTML and rewrite the element containing the picture data as a picture element at the desired position.

That is:

1. Process your Markdown into HTML.
2. Post-process the HTML to rewrite instances of picture data as `<picture>` elements.

For the first step, two options that come to mind use extended Markdown syntax: the footnote and the description list.

In either case I suppose you could include a keyword or key bit of syntax to mark the data in a way that will cause your bespoke post-processing script to recognize and act upon it. 

A __footnote__ would place the structured data _outside the flow of the main text_ (suitable if there is no post-processing) and allow almost any variety of temporary syntax for arranging that data. Another advantage is that the HTML link to the footnote, which would indicate where your script should insert the picture, can reside within a block-level element just as an `img` now can.  (The downside is that the footnote link cannot exist _without_ associated block-level content. Oh well.) Note that the keyword cannot be the footnote marker itself, as this is processed out by the Markdown script (at least in the implementations of which I'm aware).

A __description list__ would place the data in a DL element, structured either as a series of DT-DD pairs, or as the content of a single pair which you could again structure in any fashion (as with the footnote). A disadvantage is that the data will fall more within the surrounding prose than would a footnote, but advantages may exist as well.

Below are examples of the Markdown I imagine, each using `\picture-data\` as the identifier to be recognized in post-processing. To structure the data I merely remove the angle brackets and line breaks (to minimize Markdown processing) and add semicolons as delimiters. The last example builds on the standard Markdown image format and thus does not require extended syntax.

## Example 1: Footnote

    A picture[^pic1] will go inside this paragraph.

    [^pic1]: \picture-data\ source media="(max-width: 700px)" sizes="(max-width: 500px) 50vw, 10vw" srcset="stick-figure-narrow.png 138w, stick-figure-hd-narrow.png 138w"; source media="(max-width: 1400px)" sizes="(max-width: 1000px) 100vw, 50vw" srcset="stick-figure.png 416w, stick-figure-hd.png 416w"; img src="stick-original.png" alt="Human"

## Example 2: Description List with Single Term

    Lorem ipsum dolor sit amet consectetur adipiscing whatever.

    \\picture-data\\
    :   source media="(max-width: 700px)" sizes="(max-width: 500px) 50vw, 10vw" srcset="stick-figure-narrow.png 138w, stick-figure-hd-narrow.png 138w"; source media="(max-width: 1400px)" sizes="(max-width: 1000px) 100vw, 50vw" srcset="stick-figure.png 416w, stick-figure-hd.png 416w"; img src="stick-original.png" alt="Human"

    Lorem ipsum dolor sit amet consectetur adipiscing more of whatever.

## Example 3: Description List with Multiple Terms

    \\picture-data\\

    source1
    : media="(max-width: 700px)" sizes="(max-width: 500px) 50vw, 10vw" srcset="stick-figure-narrow.png 138w, stick-figure-hd-narrow.png 138w"

    source2
    : media="(max-width: 1400px)" sizes="(max-width: 1000px) 100vw, 50vw" srcset="stick-figure.png 416w, stick-figure-hd.png 416w"; 

    img
    : src="stick-original.png" alt="Human"

## Example 4: Image + Footnote

Presumably you'd like a basic one-size-fits-all-screens 'img' element to be displayed in case there is no post-processing to create a picture element. Shifting the additional source data (beyond what is required for img) into a footnote could still be a good answer:

    ![Human](stick-original.png)[^pic4]

    [^pic4]: \picture-data\ source media="(max-width: 700px)" sizes="(max-width: 500px) 50vw, 10vw" srcset="stick-figure-narrow.png 138w, stick-figure-hd-narrow.png 138w"; source media="(max-width: 1400px)" sizes="(max-width: 1000px) 100vw, 50vw" srcset="stick-figure.png 416w, stick-figure-hd.png 416w"

## Example 5: Image with Title

This variation has the advantage that the additional source info is not visible (in ordinary contexts, although it's still part of the HTML content):

    ![Human][human]

    [human]: stick-original.png '\picture-data\ source media="(max-width: 700px)" sizes="(max-width: 500px) 50vw, 10vw" srcset="stick-figure-narrow.png 138w, stick-figure-hd-narrow.png 138w"; source media="(max-width: 1400px)" sizes="(max-width: 1000px) 100vw, 50vw" srcset="stick-figure.png 416w, stick-figure-hd.png 416w"'

The reference form can be used (i.e. image info moved further down the page), as shown above. Either way, however, a distinct disadvantage of the img approach is that quotes may need to be escaped, since the value of the title attribute must be quoted and the value itself (at least as I've been showing it) contains quotes.

---

In each example above, I assumed that your post-processing script will look for `\picture-data\` and rewrite the related HTML using the string of data that follows.

In the case of a footnote, the script would need to find the related link and insert the picture element there. If HTML5 does not define `<picture>` as a block element and you wish it this one to be so, I suppose you'd need to add 'block' or something to your picture-data so that it can influence the post-processing. CSS classes and IDs can be added as well in this fashion.

Example 5, the image-with-title, is possibly the best of these suggestions — unless your preferred Markdown implementation chokes on nested quotes in image titles. (The dingus at Daring Fireball renders the double-quotes in the example as `"` entities. The parser inside the 1Writer app does this in all the examples. Okay, so your post-processor converts these back to quotes.)

Some last thoughts:

- This sort of post-processing approach frees you from having to write any HTML for your picture, let alone HTML with case-sensitive tags.
- Other Markdown options that occurred to me later include a table and nested lists, but I see little advantage (beyond some semantic correctness if they aren't processed out) and so didn't include them above.
- PHP Markdown Extra allows class and ID to be set on images. (And on code blocks. The image-source data, for typical reading purposes, is programmatic, i.e. it's code, so that would be semantically appropriate markup.) Classes and IDs can aid what we're trying to do here.
- I already use post-processing in my PHP to rewrite footnote links (so that they don't conflict with those of other blog posts on the same page) and find the lag unnoticeable.

Hoping this helps,
Thomas Humiston

> On 27 Mar 2019, at 10:22 AM, Sherwood Botsford <sgbotsford at gmail.com> wrote:
> 
> 
> I like markdown.  I use it in combination with Template Toolkit, and basically I don't have to write any html.  My webpages are static, having only the js snippet that Google analytics uses.  I would mostly like to keep it that way.  I have zero javascript experience.
> 
> I can do some degree of simple page layout using a handful of classes applied to DIVs.  
> 
> So this
> 
>     <DIV class=picr3>
> 
>     ![Shelterbelt-12][2]
>     
>     Planting a shelterbelt, or any tree project...
>     
>     ***
>     
>     </DIV>
>     [2]: /Images/Shelterbelt/Shelterbelt-12.jpg
> 
> is all the html I need to use to have an image sized to width 30% of the Content div floated to the right.  The system isn't perfect, but it resizes reasonably well, and since the page is static it caches well, and is fast to deliver.
> 
> More important to me:  I can spend time writing content, and very little tweaking layout.
> 
> The problem:  If I serve an nice desktop image to a mobile phone, download times are high.  If I serve an image of reduced resolution to make phone access quick, it looks like crap on a desktop.
> 
>  
> 
>  In Html we now have the <picture> element, combined with the srcset and size attributes.  This turns what used to be a simple img tag into this: 
> 
>     <picture>
>     <source media="(max-width: 700px)" sizes="(max-width: 500px) 50vw, 10vw"
>     srcset="stick-figure-narrow.png 138w, stick-figure-hd-narrow.png 138w">
>     
>     <source media="(max-width: 1400px)" sizes="(max-width: 1000px) 100vw, 50vw"
>     srcset="stick-figure.png 416w, stick-figure-hd.png 416w">
>     
>     <img src="stick-original.png" alt="Human">
>     </picture>
> 
> At this point, I'm looking at having to roll my own solution much along this line:
> 
> *  Replace <DIV> with <div>  On my implementation of Markdown, being between lower case tags means that the content of that tag is not Markdown processed.
> 
> * Come up with a standard naming convention, say whateverimage-L.jpg for the large version, -M.jpg for the medium version and -S. jpg for the small version.
> 
> * Pre process the resulting markdown files to generate the full <picture> element from the embedded markdown.  I think this is within my limited perl programming capabilities.
> 
> Gotchas?
> 
> This wheel has been invented already?
> 
> Better ways to approach this?  Should I bite the bullet and do this with a javascript snippet?
> 
> Some other solution I've missing in my wandering of 'a maze of twisty passages, all different' that is the internet?
> 
> 
> Regards
> 
> Sherwood
> 
> _______________________________________________
> Markdown-Discuss mailing list
> Markdown-Discuss at six.pairlist.net
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss