seth-brown / formd Goto Github PK

A Markdown formatting tool

License: MIT License

JavaScript 14.68% TypeScript 85.32%

markdown cli typescript nodejs

formd's Introduction

formd: a markdown formatting tool

formd is a CLI tool for (for)matting (m)ark(d)own that allows interconversion between the two styles of Markdown links, inline and referenced. The tool conforms to the Github Flavored Markdown spec.

Installation

npm install -g @seth-brown/formd

If the default location npm installs packages to isn't in your path, you may need to add it to your path. For example:

echo 'export PATH="$HOME/.node/bin:$PATH"' >> ~/.zshrc

Motivation

Inline Markdown is difficult to read, but useful for writing and editing because the linked text and URLs are adjacent to the words you are writing. For example:

The quick brown [fox](http://en.wikipedia.org/wiki/Fox) jumped over the lazy [dog](http://en.wikipedia.org/wiki/Dog).

Referenced Markdown is awkward while writing because it requires jumping between links within the text and the reference section of the document. However, referenced Markdown is the superior syntax for reading because URLs do not breakup the flow of words or sentences. For example:

The quick brown [fox][1] jumped over the lazy [dog][2].

formd provides the best of both worlds by allowing users to quickly toggle Markdown formats between inline while writing and referenced while reading. formd reads and writes to standard streams, so it can be adapted to a wide-range of user workflows.

Usage

formd is a command line tool, but its primary use case is with text editors or in conjunction with system tools like snipper expanders or app launchers. From the command line formd can be used as follows:

For help:

formd -h

To generate referenced Markdown use the -r flag:

formd -r < <(echo "a line of text\na link with a [link]('www.foo.com')")

To generate inline Markdown use the -i flag:

cat my-markdown.md | formd -i

Usage with Text Editors

formd can be integrated with editors like Vim. The easiest option is to call it directly from within a Vim buffer. For example:

:%! formd -r

An easier approach is to use a function to execute formd and return the cursor back to it's original position within the buffer.

" a function to execute `formd` and return the cursor back
" to it's original position within the buffer. 
" This script assumes `formd` is in your path. 
function! Formd(option)
    :let save_view = winsaveview()
    :let flag = a:option
    :if flag == "-i"
        :%! formd -i
    :else
        :%! formd -r
    :endif
    :call winrestview(save_view)
endfunction
 
" formd mappings 
nmap <leader>fr :call Formd("-r")<CR>
nmap <leader>fi :call Formd("-i")<CR>

Usage with App Launchers

formd can be invoked with app launchers like Alfred. Two Alfred workflows are provided in the repo at system/alfred/. These workflows take the contents from the clipboard and covert them to either inline or reference markdown and then paste the converted text into the front most application.

Release History

1.0.0 Initial release
2.0.0 Ported library to Typescript/Node

formd's People

Contributors

Stargazers

Watchers

Forkers

voidfiles kevinkelley n1k0 intrepidal dataduke chauncey-garrett phaufe johnlaudun ivanov kruts69 anko fnurl hbcbh1999 cmatmsu pigmonkey thebureaugroup esprengle ibuys liangruile-michela

formd's Issues

Formatting on links within parentheses

When you run formd on a link that has parentheses around it, the new formatting includes the inside parentheses.

Example:

([link](link.me)) becomes ([link][1] and [1]: link.me)

Adjacent square brackets inside code are mistakenly matched as links

Inside backticks

Input file:

`[x][y]`

Command: formd -r

Output:

`[x][1]`


[1]: y

Expected output:

`[x][y]`

Inside code blocks

Input file:

    [x][y]

(note the 4-space indent)

Command: formd -r

Output:

[x][1]


[1]: y

Expected output:

    [x][y]

Similarly for code indented by 1 tab, instead of 4 spaces—the alternative syntax.

Maybe it would be better to internally use a dedicated markdown parser like mdast rather than reimplement something that can catch all these fiddly details?

formd as a module

Very nice tool. I'd like to set up a package for Sublime Text but it would be much easier having formd as a reusable module than a command line executable :)

Feature Request: Implement the very same functionality for footnotes

Very similar to what formd does, there is the issue of two styles of footnotes: inline and reference footnotes.

I think it would be a great addition for formd to do switch between those footnote styles as well. Would make Academic Writing in Markdown much easier.

links with internal line breaks not processed

I format my markdown with tw=78 so sometimes I might get a link that has a line break in it e.g.

lorem ...                                           [this is my 
link] (url)

Currently formd doesn't recognise this as a link

Only works on Python 2.7+

OrderedDict is new in 2.7.

There's an MIT licensed drop-in replacement for 2.4+ available at http://code.activestate.com/recipes/576693-ordered-dictionary-for-py24/ and on PyPi.

I'd fork/pull request and throw that in, but that either adds a dependency or quadruples the size of formd, so I thought I'd raise it here first.

Text is truncated when reference-style links are not all at bottom of document

If you use reference-style links and add them just below the paragraph with the link, rather than putting them all at the bottom of the document, Formd loses the body text between the reference links. Here's an example to demonstrate:

# Header

Here is my first paragraph with [a link][1].

[1]: http://link-one.com

Here is my second paragraph with [another link][2].

[2]: http://link-two.com

RegEx Suggestion

The regular expression for finding links seems to be a bit loose.

self.match_links = re.compile(r"""(\[[^^]*?\])\s?             # text
                              (\[.*?\]|\(.*?\r?\n?.*?\)\)?)   # ref/url
                               """, re.MULTILINE | re.X)

For example, markdown text like this:

This morning, a friend noted a discrepancy between two recent headlines at The Mac Observer:

+ March 5: "[Apple CFO Peter Oppenheimer to Retire, Luca Maestri to Take Over][tmo1]"
+ May 7: "[PR Queen Katie Cotton Leaving Apple][tmo2]"

[tmo1]\: http://www.macobserver.com/tmo/article/apple-cfo-peter-oppenheimer-to-retire-luca-maestri-to-take-over
[tmo2]\: http://www.macobserver.com/tmo/article/pr-queen-katie-cotton-leaving-apple

[I tweeted the two headlines and corresponding URLs][t], with a single word of commentary: "Hmm". I said no more partly because I was near the 140-character limit, and partly to see what the reaction would be. Some got it, but many repliers missed my point, mistakenly thinking it was related to an exodus of executives from the company.<sup id="fnr1-2014-05-08">[1]</sup>

My point was to draw attention to the disparate job descriptions: "Apple CFO" vs. "PR Queen".

[Julia Richert pointed to][j] a similar discrepancy -- two Philip Elmer-DeWitt headlines on his weblog at CNN/Fortune/Money

will match items thus:

[Apple CFO Peter Oppenheimer to Retire, Luca Maestri to Take Over][tmo1]
[PR Queen Katie Cotton Leaving Apple][tmo2]
[tmo1]: http://www.macobserver.com/tmo/article/apple-cfo-peter-oppenheimer-to-retire-luca-maestri-to-take-over [tmo2]: http://www.macobserver.com/tmo/article/pr-queen-katie-cotton-leaving-apple \n [I tweeted the two headlines and corresponding URLs][t]
[1]</sup> \n My point was to draw attention to the disparate job descriptions: "Apple CFO" vs. "PR Queen". \n [Julia Richert pointed to][j]

To tighten up the regex, I suggest the following change, which appropriately catches all markdown links, but only markdown links:

self.match_links = re.compile(r"""(\[[^^\[\]:]*?\])\s?? # text
                              (\[[^\[\]:]*?\]|          # ref
                              \(.*?\r?\n?.*?\)\)?)      # url
                              """, re.MULTILINE | re.X)

Clearly, the only real change is to add to the characters that cannot be within the linked text or in the reference id.

Markdown-links starting at start of line truncate following text

After my comment to Issue #4 I updated to the latest version of formd, commit be5d17f237dddd1970c6d94eaf175fa7c5378167
and this fixed all my footnote related problems. Thank you again for your quick
fix.

Now I noticed a problem with the link conversion in a rather lenghty post of
mine. Whenever a link is at the start of a line, the following body text gets
truncated. Putting any character in front of the link returns the full
functionality of formd.

Let me demonstrate with this example file formd_test_file.markdown:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.

[Link to google][1]

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.

[Link to formd][2]

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.


[1]: http://google.com
[2]: http://drbunsen.github.com/formd/

Output of cat formd_test_file.markdown | formd -r:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.


[1]: [1]
[2]: http://drbunsen.github.com/formd/

Output of cat formd_test_file.markdown | formd -i:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.

All text after the first link gets truncated. In case of formd -r the
reference at the bottom of the file gets turned into [1]: [1]. This is, how
I first noticed the problem, because I write my Markdown links inline style and
convert them occasionally to the reference style.

Putting a space before the first link, pushes the problem down to the next link
in the file and is still killing the first link:

cat formd_test_file.markdown | formd -r:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.

 [Link to google][1]

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod
tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At
vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
sea takimata sanctus est Lorem ipsum dolor sit amet.


[1]: [1]
[2]: http://drbunsen.github.com/formd/

In the above output the second link and the complete third paragraph are
missing. The reference of the second link is still there, though...

Maybe this is somehow related to Issue #6?

I checked it against the formd version from the former commit
4b8ab19b50025fa1e20f5f20919841a1d56dc250 and this worked fine. But misses, of
course, the footnote support...

I diffed the two versions and saw, that the differences are only related to the
self_match_links and self_match_refs part of formd. Yeah, makes sense.

However, it seems that my Python-Fu is not strong enough to come up with
a regex, which makes footnotes and links starting at the beginning of a line
working.

Would you be so kind, to have another look at this fine piece of software? Thank you very much for your time and efforts.

Dennis

formd flipping mangles MultiMarkdown footnotes

Using formd to flip link style on a document containing MultiMarkdown footnotes will mangle the footnotes. Specifically, while the inline footnote numbering is retained (in most cases – consecutive footnote numbers retain only the first), the body of the fist footnote will be concatenated to the text if there are several footnotes, while the following get deleted (as does a lone footnote body).

As reproducing this will be easier than trying to describe it, I have prepared two test documents, formd inline link test document and formd reference link test document – I suggest downloading those and trying out what happens on flipping to get a clearer grip on the issue.

Colon following link results in data loss

Colons that follow links may result in lines removed from the expected output.

Input file:

* [link text](http://link.com)
* [link 1 text](http://link1.com):

Command formd -r

Output:

* [link text][1]


[1]: http://link.com
[2]: http://link1.com

Problem: the line containing link 1 text is missing from the output.