Git Product home page Git Product logo

tufte-markdown's Introduction

Tufte-Markdown

This project is still in a very early stage and has not been tested extensively with a wide-range of documents use at your own risk

This project aims to convert markdown to HTML (or React) in a way that it can be used with tufte-css - a set of stylesheets that aim to emulate the Style of the Handouts of Edward Tufte.

In the end it looks like this: https://edwardtufte.github.io/tufte-css/

The markdown-syntax is taken from the great tufte-pandoc-css-project, but not yet fully implemented. This project will aim to emulate the syntax there as much as possible.

Markdown-Parsing and -Conversion is done usingremark

Installation

$ npm install @tufte-markdown/parser

Usage

import configureParser from '@tufte-markdown/parser'

const options = {
  react: false,
}

const parse = configureParser(options)
const result = parse('## Heading **strong** *emphasis*')

console.dir(result)

// Output:
// <section><h2 id="heading-strong-emphasis">Heading <strong>strong</strong> <em>emphasis</em></h2></section>\n'

🖐 Note: The parser currently only outputs document fragment to make it look right you will have to wrap it in an article-tag

Options

options.react (Default: false) - Output a react-syntax-tree instead of HTML using remark-react

Syntax

You can get an overview of the possible syntax in the base file for the full example

Limitations/Differences to tufte-pandoc-css

  • Currently cannot parse markdown in the footer of a blockquote
  • tufte-pandoc-css uses ^[{-} Text] for inline-sidenotes which would need custom parsing in remark. This project uses [^{-} Text] which seems to be more inline with how the other side-/marginnotes are defined

Example:

tufte-pandoc-css

<figure>
^[{-} From Edward Tufte, *Visual Display of Quantitative Information*, page 92.]
![Exports and Imports to and from Denmark & Norway from 1700 to 1780](img/exports-imports.png)
</figure>

tufte-markdown

<figure>
[^{-} From Edward Tufte, *Visual Display of Quantitative Information*, page 92.]
![Exports and Imports to and from Denmark & Norway from 1700 to 1780](img/exports-imports.png)
</figure>

Motivation

To provide an alternative to tufte-pandoc-css within the node-ecosystem to make it easier to integrate with libraries like React

tufte-markdown's People

Contributors

jeffrafter avatar luhmann avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

tufte-markdown's Issues

throws on an empty figure tag

Suppose one places an empty figure tag

<figure></figure>

I get an error

TypeError: Cannot read property 'type' of undefined
    at parseMarkdown (test\node_modules\@tufte-markdown\remark-figure-parser\dist\remark-figure-parser.cjs.js:15066:52)
    at Of.figureTokenizer (test\node_modules\@tufte-markdown\remark-figure-parser\dist\remark-figure-parser.cjs.js:15040:22)
    at Of.tokenize [as tokenizeBlock] (test\node_modules\remark-parse\lib\tokenizer.js:58:18)
    at Of.parse (test\node_modules\remark-parse\lib\parse.js:33:20)
    at Function.parse (test\node_modules\unified\index.js:271:45)
    at pipelineParse (\test\node_modules\unified\index.js:23:16)
    at wrapped (\node_modules\trough\wrap.js:25:19)
    at next (test\node_modules\trough\index.js:58:24)
    at Object.run (test\node_modules\trough\index.js:32:10)
    at executor (test\node_modules\unified\index.js:365:16)

I am not sure of how the AST works but I am guessing you need to test for result.children array not being empty????

Markdown content in html block tags is not converted

By convention markdown syntax inside block elements is not processed. And remark respects those conventions (see rehypejs/rehype-raw#8).

A number of items such as <footer> inside blockquotes, epigraphs etc. do not work as expected when they contain markdown (for some reason beyond my understanding markdown inside <figure> tag works).

Even in your own tests some items are not being rendered correctly. See for example, output for section.md in tests:

> [It is] notable that the Feynman lectures (3 volumes) write about all of
> physics in 1800 pages, using only 2 levels of hierarchical headings: chapters
> and A-level heads in the text. It also uses the methodology of
> <em>sentences</em> which then cumulate sequentially into <em>paragraphs</em>,
> rather than the grunts of bullet points. Undergraduate Caltech physics is very
> complicated material, but it didn't require an elaborate hierarchy to
> organize.
>
> <footer>
> [Edward Tufte, forum post, 'Book design: advice and examples' thread][quote-cite]
> </footer>

[quote-cite]: http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0000hB

is rendered as:

<blockquote>
<p>[It is] notable that the Feynman lectures (3 volumes) write about all of
physics in 1800 pages, using only 2 levels of hierarchical headings: chapters
and A-level heads in the text. It also uses the methodology of
<em>sentences</em> which then cumulate sequentially into <em>paragraphs</em>,
rather than the grunts of bullet points. Undergraduate Caltech physics is very
complicated material, but it didn’t require an elaborate hierarchy to
organize.</p>
<footer>
[Edward Tufte, forum post, 'Book design: advice and examples' thread][quote-cite]
</footer>
</blockquote>

Notice that the footer remains unprocessed!

We either need to change conventions in conversation with @jez or hope that remark supports non-standard syntax through a plugin.

Markdown fragments without Headings render without section

Thanks for the great work on this library! I'm in the process of wiring up to the eleventy static site generator as a replacement for the built-in markdown parser, and everything seems to be working well. One hitch, though: Markdown documents with no second-level headings never get the necessary section tag as a wrapper, and the layout files. For example:

console.dir(parse('Opening paragraph\n## Heading **strong** *emphasis*'))

// Output:
// <section><p>Opening paragraph</p></section> <section><h2 id="heading-strong-emphasis">Heading <strong>strong</strong> <em>emphasis</em></h2></section>

console.dir(parse('Opening paragraph\n\nSecond paragraph'))

// Output:
// <p>Opening paragraph</p> <p>Second paragraph</p>

I'm not sure if this is intentional; in theory it's possible to check the output for a missing <section>, but it seems like adding the wrapper makes sense even if there's no second-level heading?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo 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.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.