Markdown to this? about tufte-css

[jez]

For what it's worth: I just put together tufte-pandoc-css to solve the problem of writing side notes in Markdown. It's just a showcase of how to use a custom Pandoc filter I wrote called pandoc-sidenote.

To see it in action:

• A re-implementation tufte-css/index.html in Pandoc-flavored Markdown
• A demo of some other Pandoc features, like syntax highlighted code blocks.

[vieiro]

Just found this thread through Google

You guys may want to take a look at xmark: that converts markdown to Tufte-CSS vía XSLT.

Pandoc offers templates to build on, so creating a Tufte pandoc template should be straightforward.

@langford turns out there is already a Tufte template for Pandoc, see my comment here for details on converting Markdown/Multi-Markdown into Tufte styling: #30 (comment)

[fasiha]

@xhn35rq after looking into it a bit, pandoc templates seem like the wrong avenue for this functionality: a template is given a $body$ string and pretty much expects to just put text before and after it, and doesn't seem intended to actually manipulate the generated-from-markdown text. You would use pandoc custom writers which you can write (hallelujah) in Lua. I've written a barebones custom writer that just implements sidenotes and adds the article tag: see gist. I hope to expand this as I continue writing tufte-css to include all provided features—ideally without having to modify anything about pandoc markdown or its readers.

(For completeness I might mention pandoc filters as something that might eventually be needed to fully produce tufte-css-enabled HTML from pandoc markdown, but probably only for very tricky things. Filters manipulate the AST, before an AST is given to a custom writer. The right place to do tufte-css-style sidenotes was in the custom writer, not as a filter.)

@fasiha good work. You've made a promising start here. 👍

[fasiha]

I don't think there's a readily-available equivalent to tufte-css sections in Markdown, i.e., a grouping of paragraphs and headings. But I think I like the idea of sections, I think having an extra level of document organization will be helpful down the road.

Any suggestions from the community how one could indicate sections in Markdown?

[vyp]

@fasiha What about a filter that takes heading elements and all the paragraph elements up to the next heading element? Then wrap these in <section> (or some custom <div>) tags and apply the desired css to this?

[fasiha]

Thank you for weighing in @vyp. From my reading of the tufte-css front-page, section can capture more than one heading, or paragraphs with no heading. That is, it's not just a heading-and-contents container. In my document, I'm just embedding <section> as raw HTML in the Markdown for now—for this, I think I can accept raw HTML.

[vyp]

@fasiha Ah sorry you are correct. Because a section is defined as a "logical grouping of text and headings", it's impossible to determine what exactly a section is in a document without human input (i.e. us actually marking up the sections as semantic information, just like how we mark up with emphasis with asterisks or underscores). And yes, I'm not aware of any pre-existing syntax for these "sections" in any markdown flavour, so good catch.

Using raw <section> tags is the best possible thing to do in this case (other than defining your own markdown-like syntax for it and writing a parser for it).

---

Another way to go would be to use the fact that tufte says it uses h2 for "section headings", so perhaps a "section" can be defined as a h2 tag and everything up to the next h2 tag and so on. But I'm not sure if this is what the author of tufte intended.

[daveliepmann]

H2 elements are not reliable sources of section demarcation. For instance, some documents use "newthought" spans instead. I am sure other variations will emerge in the wild.

On 8 Ağu 2015, at 23:49, vyp [email protected] wrote:

@fasiha Ah sorry you are correct. Because a section is defined as a "logical grouping of text and headings", it's impossible to determine what exactly a section is in a document without human input (i.e. us actually marking up the sections as semantic information, just like how we mark up with emphasis with asterisks or underscores). And yes, I'm not aware of any pre-existing syntax for these "sections" in any markdown flavour, so good catch.

Using raw

tags is the best possible thing to do in this case (other than defining your own markdown-like syntax for it and writing a parser for it).

Another way to go would be to use the fact that tufte says it uses h2 for "section headings", so perhaps a "section" can be defined as a h2 tag and everything up to the next h2 tag and so on. But I'm not sure if this is what the author of tufte intended.

—
Reply to this email directly or view it on GitHub.

[vyp]

I guess if anyone wants to avoid using <section> tags in their markdown, some syntax similar to <hr>'s may not be difficult to implement. The syntax for <hr>'s is basically "three or more hyphens, asterisks, or underscores on a line by themselves". So for example you could arbitrarily define a "section" demarcation as "three or more equals signs" (or whatever you prefer), and then use a pandoc filter to wrap everything between each couple of these paragraphs with only equals signs.

I only chose "a line of equals signs" because I guess this is what dividing sections with plain text would look like? And because pandoc markdown will parse this as only a paragraph, meaning your filter can just check every paragraph if it only has equals signs or not, and if it's only made up of equals sign, assume that this is part a section demarcation.

[coppeliaMLA]

Hi all (and thanks to @daveliepmann for pointing me to this thread). You might be interested in my glasseye package in which I've used the Tufte.css (so thanks to everyone for that) and in which I've aimed to integrate markdown, d3 and the Tufte layout. At the moment it's very much a prototype with lots of corner cutting. When I have a moment I'd like to clean up the code and rationalise the design a bit (at that point I'll be trawling through your comments on the css). But I wanted to see if it was worth doing first and I think it is. Anyway would love any feedback.

[carsonyl]

Would reStructuredText be more amenable than Markdown to the sort of annotations that are needed here?

[vyp]

@coppeliaMLA Thanks for mentioning glasseye, it's incredible work.

@rbcarson I'm not OP, but if the question's directed at everyone here and you want my opinion, I'm personally not that familiar with restructuredtext so I cannot really say. But you may be right, the basic markdown syntax created by Gruber, Swartz and co I think was inspired from how people wrote (plain text) emails 'back then'. So it only started off as complex (or as 'able') as the average email message could get, not a research paper or some other form of writing that uses a lot of sidenotes or otherwise follows or makes sense with Tufte's style.

So over the years, there's only so much other type of syntax you can cram into "markdown" because the whole point of it is that it's supposed to be readable in plain text form. How do you convey sidenotes visually in plain text? Nevertheless, I feel pandoc's extended markdown has done a really good job in this regard.

So I think restructuredtext has something called directives or something, which allows you build syntax (or something?) for a particular type of data? If that's somewhat the case, yes, I would think restructuredtext is probably more amenable here. But as I said, I don't have much experience with it, so I cannot help you any further.

[langford]

restructuredText would be useless for my purposes, which are projects already documented in markdown

On Aug 17, 2015, at 4:24 AM, vyp [email protected] wrote:

@coppeliaMLA Thanks for mentioning glasseye, it's incredible work.

@rbcarson I'm not OP, but if the question's directed at everyone here and you want my opinion, I'm personally not that familiar with restructuredtext so I cannot really say. But you may be right, the basic markdown syntax created by Gruber, Swartz and co I think was inspired from how people wrote (plain text) emails 'back then'. So it only started off as complex (or as 'able') as the average email message could get, not a research paper or some other form of writing that uses a lot of sidenotes or otherwise follows or makes sense with Tufte's style.

So over the years, there's only so much other type of syntax you can cram into "markdown" because the whole point of it is that it's supposed to be readable in plain text form. How do you convey sidenotes visually in plain text? Nevertheless, I feel pandoc's extended markdown has done a really good job in this regard.

So I think restructuredtext has something called directives or something, which allows you build syntax (or something?) for a particular type of data? If that's somewhat the case, yes, I would think restructuredtext is probably more amenable here. But as I said, I don't have much experience with it, so I cannot help you any further.

—
Reply to this email directly or view it on GitHub.

[fasiha]

@coppeliaMLA very interesting!: use pandoc to output HTML with special tags, and then as a second stage, use another program to expand the special tags to Javascript and HTML. My approach has been to make a Pandoc custom writer that consumes the special tags, effectively doing glasseye.py in Lua, using the Pandoc AST instead of BeautifulSoup parsing, but it looks like glasseye is basically working just fine. I'll try to glasseye-ify my documents and let you know on its repo about any issues. Things that are hard to do in a Pandoc writer might be easier to do post-processing, and vice versa, but the only way to find out is to write a bunch of documents :)

[coppeliaMLA]

@fasiha thanks. Your way does sound more efficient and I think possibly I might head that direction in the end. I went for python as it allowed me to create a quick prototype. But as you say experimenting on lots of docs will hone the best method. I'm planning on using it for as much of my day to day work as possible to see where it gets me. Would be great if you could give it a try. Love to hear how it goes!

See #31 and also #58

[daveliepmann]

@jez Cool! I'll see if I can find a project to give this a whirl with.

[ryan-mars]

@vieiro wow this is nice. Great work 👍🏻