Sidenotes/comments in markdown writing

Maybe something like this exists:

When writing a document in markdown, there are sometimes notes I would add that are not part of the main text (e.g. return here to check; this paragraph solves X; this covers topic Y). In Word or Googledoc I would make them as comments perhaps. Markdown commented areas are useful (<!-- —>), but crowd the text in manuscript writing.
Ideally this would be something like Tufte style margin notes / sidenotes.

Do any packages cover this? Which solutions would you recommend to make notes not part of main text, so they wouldn’t crowd it?

Would a package like this be possible? I.e. translating part of markdown to show on the right margin, or making a file of notes that is in sync with the main text? Maybe even just in pdf-preview of the .md?

Possibly simply turning off soft wrap (with character limit) for individual lines, e.g. by “!s” at the start could allow notes beyond the soft wrap margin. Even better would be if same key could start left-aligned from margin already. Even better-better if this would wrap with window limit or another arbitrary soft wrap character limit.

The notes would then be easily distinct from main text, and would be visually easy to notice in themselves too.

Thanks!

You can try installing markdown-footnote to add notes at bottom of your markdown document. I use markdown-preview-enhanced and with pandoc installed you can specify “frontmatter” (yaml) which pandoc picks up.

Another approach is to create reveal.js presentation (again from markdown-preview-enhanced output options) with speaker notes.

1 Like

This works well for footnotes indeed! I am now thinking, could the markdown-preview-enhanced .css or styles.less be edited to include also sidenotes, e.g. based on this https://edwardtufte.github.io/tufte-css/.

Unfortunately I am a css newbie, so not sure, if or how this could be done.

If the main text were given like 80% margin in preview, and sidenotes could be put on that extra 20%, that would work great!

In R-markdown there are sidenotes. But I have not tried these yet.

Or perhaps try this.

1 Like

The jquery option seems promising. Can’t seem to get it to run, just beyond my skills now. On the other hand, not sure if this could function within Markdown preview already? Ideally looking for a solution that would easily update while editing.

Yeah, something like Rmarkdown does for tufte in atom would be brilliant! I suppose atom doesn’t just read Rmarkdown syntax for this. Couldn’t find a way for now.

Pursuing the quest the jquery.sidenotes script demo is promising.

Since pandoc can be used to convert markdown to html I reasoned that jquery.sidenotes can be embedded through a pandoc html template.

There are ideas to be followed up in the pandoc-discuss group.

I have tried embedding jquery.sidenotes scripts into the html preview output from markdown-preview-enhanced but no sidenotes working as yet.

Here is a list of pandoc templates.

Here is a sample script found for md to html conversion via pandoc.

1 Like

Just reporting progress that I have worked out how to export markdown from Atom to create an html output with sidenotes as in above demo. The only issue is that this is not yet an inline preview where edits can be previewed on the fly (as in markdown preview panel). The markdown has to be processed by a script and processed html viewed in browser. But it works exactly as the demo.

1 Like

Hey @d_l, that sounds very promising!! Thanks for looking into it! I wonder if we can tag the authors of the Markdown Preview Enhanced here, maybe it’s possible to fill in the gaps of what is missing. @shd101wyy ?

(I will be offline for a couple of days, but I will check back then!)

I have now looked into embedding the scripts into markdown-preview-enhanced package and the html preview is rendered here …

$HOME/.atom/packages/markdown-preview-enhanced/node_modules/@shd101wyy/mume/out/src/markdown-engine.js

The html content is preprocessed in a var html around line 900.

The sidenotes scripts and div elements can be injected here but due to the narrow width of the Atom html preview panel the sidenotes do not take effect (they only appear with full width browser and revert to footnotes for smaller widths as explained in the demo). However, see [Later edit] below which solves this issue.

Also there is a possibility that these edits to markdown-engine.js will be overwritten by any package update.

I will embed for my own purposes since the TOC is output in the html output. I will suggest this as an issue to the package developer.

[Later edit] I later solved the issue about narrow width of markdown preview pane by installing the package maximize-panes. This allows the markdown preview pane to be maximized to full window width and allowing side notes to be displayed.

Another package I found - markdown-scroll-sync - allows the markdown pane and preview pane to be scrolled and they stay in sync.

1 Like

That’s so cool!! So it works on your computer? Thinking of making the files/workflow public as a package/repository?

I don’t want to publish a package since I would then have responsibility for maintaining it. Instead I will set out the workflow I used on Ubuntu.

We start by reviewing the demo site by author Andrew Clark.

http://acdlite.github.io/jquery.sidenotes/#sn:notes

Unfortunately the link to andrewphilipclark.com is broken so the author could not be contacted. Full credit to the author for the scripts below.

I did track down his contributions here …

https://devhub.io/developer/acdlite

https://devhub.io/repos/acdlite-andrewphilipclark.com

https://github.com/acdlite/jquery.sidenotes

License
Copyright 2013 Andrew Clark
Licensed under the MIT License

If we right click on the demo browser page and view source we see the links to the various scripts in head and foot.

view-source:http://acdlite.github.io/jquery.sidenotes/#sn:notes

These look like this in …

  <link rel="stylesheet" href="/jquery.sidenotes/css/main.css">

    <script src="/jquery.sidenotes/components/jquery/jquery.min.js"></script>
    <script src="/jquery.sidenotes/components/jquery.sidenotes/lib/jquery.sidenotes.min.js"></script>
    <script src="/jquery.sidenotes/components/responsejs/response.min.js"></script>
    <script src="/jquery.sidenotes/components/mousetrap/mousetrap.min.js"></script>
    <script src="/jquery.sidenotes/components/highlightjs/highlight.pack.js"></script>

And at the very bottom of the view source page … we see …

<script src="[/jquery.sidenotes/js/footer.js](http://acdlite.github.io/jquery.sidenotes/js/footer.js)"></script>

In addition there are three div containers at the top

<body>

<div class="site-content">
<div class="page container">
<div class="page__content">

and at the bottom … closing these div containers …

</div>
</div>
</div>

<script src="/jquery.sidenotes/js/footer.js"></script>
</body>
</html>

Now to guard against these scripts being lost I downloaded all of them and uploaded as CDN resources. Note that I cannot guarantee that they will remain indefinitely in this CDN repo of my creation. Create your own free CDN account and transfer them. Or download into localhost.

I found that all that is necessary is to create three blocks of code

  1. The top block (referring to CDN scripts)
  2. The inner block (markdown output by pandoc as html)
  3. The bottom block (referring to CDN scripts).

These can then be joined by a simple python script to create an html page.

Converting markdown to html (the inner block above) does not have to go through the markdown-preview-enhanced package.

We can use pandoc to create simplified markdown -> html. The output from markdown-preview-enhanced is too complicated with many options included. I concluded for my usage that it is not worthwhile following that route.

If we refer to an earlier link in this thread … referring to use of pandoc … we can apply this command to a markdown file (e.g. input.md)…

pandoc -f markdown -t html5 -o output.html input.md

This creates a simplified block of html5 code which can now be joined with top and bottom blocks and previewed in browser.

Here is the python script I use to join the three blocks of code …

#!/usr/bin/env python

with open('output.html', 'r') as file:
    inner = file.read()
    file.close()

top = """
<!DOCTYPE html>
<html>
<head>
<title>testing sidenotes</title>
<link rel="stylesheet" href="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560947445/samples/main_nh5vkz.css">
<script type="text/javascript" src="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560947727/samples/jquery.min_gijs8k.js"></script>
<script type="text/javascript" src="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560947806/samples/jquery.sidenotes.min_yy8a6f.js"></script>
<script type="text/javascript" src="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560948049/samples/response.min_agsmtj.js"></script>
<script type="text/javascript" src="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560947973/samples/mousetrap.min_ngq5th.js"></script>
<script type="text/javascript" src="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560947573/samples/highlight.pack_nyag93.js"></script>
</head>
<body>

<div class="site-content">
<div class="page container">
<div class="page__content">
<h1 id="jquerysidenotes">jQuery.sidenotes</h1>
"""

bottom = """
</div>
</div>
</div>

<script type="text/javascript" src="https://res.cloudinary.com/dp7oy5sht/raw/upload/v1560947891/samples/footer_vbff7b.js"></script>

</body>
</html>
"""

html = top + inner + bottom
print(html)

I will just add here that I am finding it more logical to use yaml (front matter) in markdown-preview-enhanced to be used as Pandoc custom output.

More information here.

The aim is to use a Pandoc HTML template where the “top” and “bottom” code blocks described previously for jquery.sidenotes are included in the Pandoc template.

I will update when it works.

Thanks a lot!!! I followed the instructions, and finally got it to work on html export as you said. (Pandoc worked right away. I also updated the preview enhanced by adding the lines near line 900 in html. This is only until next update, I know, but possibly same could be done again.)

One extra detail: I had to edit markdown-it-footnote.min.js file to have <a href> before <sup> for the footnotes, as the default order for some reason broke the sidenotes.

I tried updating the generateHTMLTemplateForPreview() in the same way as generateHTMLTemplateForExport(), but was not successful. Did you succeed in having the sidenotes visible already in preview?

As ideally, I would like it visible already in preview, as it is more of a writing tool than publishing tool in the way that I have in mind. The main function is simply to have something like “comments” in docx or gdoc.

For the width problems - I imagine, the width that triggers between sidenotes and inline notes could somehow be changed to match the expected size?

Also, long term - any idea how we could get the sidenotes to the right of the text as in Tufte, instead of left?

Although I did suggest going down very deep into the engine room (although this workflow shows how the engine works) i have concluded that there is more flexibility in using frontmatter with an html template to arrive at the end delivery.

Another experiment (to add to the puzzle) is referring to

Enhance parser

https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/extend-parser.md

Edit parser.js

Run Atom command: Markdown Preview Enhanced: Extend Parser command.

Then edit the parser.js file.
parser.js file is located at ~/.mume/parser.js

I will look at the layout to switch sidenotes from left to right.

Somehow extending the parser might be cleaner for sure.

I had a look at the left-to-right too. It’s all in main.css, content should be set float:left
.post__content,.post__title,.post__footer,.page__content,.page__title,.page__footer{width:74.57627%;float:left}
and
aside should be set float:right, and positions changed, e.g. .post aside,.page aside{float:right;clear:right;width:35.89744%;width:35.89744%;margin-right:-75.89744%;position:relative;right:38.46154%}} worked ok.

Resizing is done with min-width and max-width. E.g. changing the values from 1000px to 100px, makes sidenotes also work on narrow cases.

Any idea how the Extend parser could be used to implement these?

First rough thought off the top of my head is to try amending these using pandoc --css=FILE argument. This can be set in front matter in your markdown document (see custom Pandoc reference earlier). pandoc_args: [ "--css=FILE" ]

In terminal run pandoc --help to print options.

I have not got around to testing this idea. This of course bypasses the Extend parser option. However this idea might only apply when exporting the html page and not dynamically inline as you require.

1 Like

I also posted the idea for the feature on the package repository, maybe this may help the case.
https://github.com/shd101wyy/markdown-preview-enhanced/issues/1157

Yet another …

I thought of another option that we might export a custom HTML via pandoc (since this works) then preview it (with sidenotes) in an internal pane in Atom.

I searched this discussion forum

and found reference to browser-plus

And this link found during the search gives some further tips on tuning markdown-preview-enhanced

With browser-plus now installed we can then have two Atom workflow scenes.

  • Atom with side-by-side panes: markdown (raw) and markdown (preview).

  • Atom with side-by-side panes: pandoc exported html and browser-plus pane.

We can now devise a script to toggle between these two scenes. It is still not an auto preview at time of writing markdown but it is as near as possible without deeper hacking. Perhaps the package developer might come up with fresh ideas.

1 Like

Another line of attack which has been overlooked …

Start by saving Tufte CSS page you referred to earlier into an Atom project folder.

View it in Atom pane using browser-plus and also maximize-panes.

Now the work begins to link this template into the markdown workflow.

Explore Pandoc templates which are compatible with tufte.

It seems that these threads can be drawn together.

1 Like