Comments (21)
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.
from tufte-css.
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.
from tufte-css.
Pandoc offers templates to build on, so creating a Tufte pandoc template should be straightforward.
from tufte-css.
@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)
from tufte-css.
@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.)
from tufte-css.
@fasiha good work. You've made a promising start here. 👍
from tufte-css.
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?
from tufte-css.
@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?
from tufte-css.
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.
from tufte-css.
@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.
from tufte-css.
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.
from tufte-css.
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.
from tufte-css.
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.
from tufte-css.
Would reStructuredText be more amenable than Markdown to the sort of annotations that are needed here?
from tufte-css.
@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.
from tufte-css.
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.
from tufte-css.
@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 :)
from tufte-css.
@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!
from tufte-css.
from tufte-css.
@jez Cool! I'll see if I can find a project to give this a whirl with.
from tufte-css.
@vieiro wow this is nice. Great work 👍🏻
from tufte-css.
Related Issues (20)
- Tables are all black HOT 2
- navbar support/advice? HOT 1
- links look weird when highlighted HOT 2
- tufte.css and tufte.min.css have different update dates HOT 1
- Inconsistent spacing due to inline labels as sidenote numbers HOT 1
- dark mode HOT 4
- Sidenotes on list items are misaligned
- Lists in sidenotes have body-sized fonts.
- Figcaption text overlays the image on fullwidth iframe-wrapper
- Apply section style to header and footer elements, too
- Embedding superscripts breaks line height.
- Anything in the margin disappears with narrow browser window HOT 2
- Sidenote indexing HOT 8
- .margin-toggle:checked + .sidenote ... {vertical-align: ...}
- Underlines missing at certain zoom levels HOT 8
- sidenote becomes footnote
- Using srcset inside fullwidth figure renders an image that is not full width
- Darkmode background is too dark HOT 2
- Does tufte-css play nicely with screen readers? HOT 1
- Academicicons are very strangely underlined HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from tufte-css.