
Markdownfmt – Like gofmt, but for Markdown - shurcooL
https://github.com/shurcooL/markdownfmt
======
dfc
I am not sure I completely understand the use case but I am intrigued. I ran
the following enough times that I finally aliased it to `prettymd`:

    
    
      $ pandoc -t markdown --atx-headers --no-wrap uglyfile.md 
    
    

That has been my go to way to clean up some of my crufty markdown formatting.
I have a variant `spretyymd` that pipes the output to aspell. Obviously this
does not replace the file in situ or create diffs. In situ pipe processing is
always risky sounding enough that I never thought about doing it.

I wish someone would write an updated par with better documentation.

~~~
carterschonwald
pandoc is AWESOME. Also pandoc actually got a haskell.org gsoc slot, which i'm
really happy about (I helped make it happen)

~~~
dfc
I can not say enough about pandoc. Atleast once I week I say "Why didn't you
just pandoc -x -y -z it?" I am looking forward to the orgmode reader
developments.

~~~
carterschonwald
This is actually the first summer pandoc got a gsoc student to! (via
haskell.org umbrella org). A lot of great work will be landing this summer,
including some neat support for URL encoded inline images (and a bunch of
other great things)

------
programminggeek
Can someone make a fmtfmt, like gofmt but for fmt's? It might make it easier
to just crank out one for your favorite language.

------
shurcooL
I figured now was as good time as any to post this, after seeing jsfmt posted
today.

I've been dogfooding this for about a month for all my Markdown (mostly GitHub
README.mds, comments to issues, etc.), and by now it's stable to cover my
(admittedly, more basic) use cases of Markdown. I don't have explicit support
for exotic Markdown features like tables at this time.

The Atom package has 100+ downloads by now, and I've only had 1 issue reported
so far, so I'd be very curious to actually learn how many other people use it.

~~~
NateDad
btw, I don't know if it's just me, but I found it confusing that you had
main.go in the subfolders... I generally assume main.go is only used in
packages are that are executables, so it looked like the project had 3
executables in it.

------
ihaveqvestion
This seems interesting, but I'm not sure what formatting it would actually
apply to a given Markdown document - could you add examples to the readme?

~~~
shurcooL
I've made an example gif for the Atom package:

[https://raw.githubusercontent.com/shurcooL/atom-markdown-
for...](https://raw.githubusercontent.com/shurcooL/atom-markdown-
format/master/Demo.gif)

There are also some examples in tests:

[https://github.com/shurcooL/markdownfmt/blob/d472cbc9d6118d6...](https://github.com/shurcooL/markdownfmt/blob/d472cbc9d6118d67c4f6c8dabc498b2697be389d/markdown/main_test.go#L14-L51)

~~~
dfc
I can live with condensing numbered lists and removing the blank lines between
items. Unwrapping plain text paragraphs is worse but not the end of the world.
We start to toe the line with unwrapping my blockquotes. You went way past
that line when you removed the empty line at the end of the file.

~~~
shurcooL
> Unwrapping plain text paragraphs is worse but not the end of the world. We
> start to toe the line with unwrapping my blockquotes.

What do you mean by "unwrapping"? Can you give an example please. I don't
think it should be doing any unwrapping; blockquotes should be preserved (and
nicely formatted) [1].

> You went way past that line when you removed the empty line at the end of
> the file.

It makes sure the last line has an ending newline, nothing more, nothing less.
Any extra newlines are not visible in the generated HTML.

[1]
[https://github.com/shurcooL/markdownfmt/blob/d472cbc9d6118d6...](https://github.com/shurcooL/markdownfmt/blob/d472cbc9d6118d67c4f6c8dabc498b2697be389d/markdown/main_test.go#L94-L98)

~~~
dfc
Example text (example.md):

    
    
      Alice wants to conduct a survey of her customers. She wants to restrict
      access to her customers (ie select subset of people) and she wants
      customers to be able to answer openly and not worry about reprisals.
    
      > Is there a magic token that Alice can distribute to her customers
      > (Bob,Carol,etc) that demonstrates their membership in survey pool and
      > protects the anonymity of their responses?
    
    

Transcript:

    
    
      dfc@ronin:~$ wc example.md
        8  67 395 example.md
      dfc@ronin:~$ .gopath/bin/markdownfmt example.md > gofmt.md
      dfc@ronin:~$ wc gofmt.md
        3  65 390 gofmt.md
      dfc@ronin:~$ cat gofmt.md
      Alice wants to conduct a survey of her customers. She wants to restrict a**SNIP**
    
      > Is there a magic token that Alice can distribute to her customers (Bob,**SNIP**
      dfc@ronin:~$
    
    

I truncated the lines in the cat gofmt.md because long preformatted colums
kill HN readability. That file was 7 lines of pristine markdown with a
trailing newline. markdownfmt turned it into three lines total.

    
    
      dfc@ronin:~$ pandoc -t markdown -o pandoc.md example.md
      dfc@ronin:~$ wc pandoc.md
      8  67 395 pandoc.md
      dfc@ronin:~$
    
    

I am not sure what you mean by "It makes sure the last line has an ending
newline, nothing more, nothing less. Any extra newlines are not visible in the
generated HTML." I thought this was a markdown formatting tool?

Here is a hypothetical--but common--workflow that this destroys: Author keeps
multiple chapters of book in separate files for easy editing and revision
control. When it is time to publish text the author executes:

    
    
      $ cat 1.md 2.md 3.md 4.md |publishmd --some-options
    

You killed my chapter titles.

~~~
shurcooL

      > $ cat 1.md 2.md 3.md 4.md |publishmd --some-options
      >
      > You killed my chapter titles.
    

I did not consider such a use case. Currently, markdownfmt works on an
individual file/stdin and considers that to be the entire Markdown; it does
not know that you're planning to concatenate more files.

It would work fine if you passed `cat 1.md 2.md 3.md 4.md` as input, but
removing excess newlines at the end of individual Markdown files will ruin the
concatenated result.

It's similar to an issue that goimports also has [1].

I'll think about it, perhaps something can be done to solve this.

[1]
[https://code.google.com/p/go/issues/detail?id=7463](https://code.google.com/p/go/issues/detail?id=7463)

~~~
dfc
Is saying this is similar to an issue in goimport a sly way of saying
markdownfmt "works on a file-by-file basis like gofmt; and as such it does not
and cannot know that file a.go and b.go belong to the same package. Put
another way, this is a user error for the tool as is."?

That explanation does not really make sense. I want markdownfmt to work on the
file chapter1.md and the following day after editing chapter 2 I want to
process chapter2.md. markdownfmt never needs to know and never will know that
I use chapter1.md and chapter2.md together. When I am done I am going to feed
chapter[1-X].md to another tool for publishing. But I cant because I used
markdownfmt on a file by file basis and it damaged my files.

Every large book I have seen that uses markdown uses this chapter (or smaller)
as file workflow. The biggest example that comes to mind is the progit book:
[https://github.com/progit/progit/tree/master/en](https://github.com/progit/progit/tree/master/en)

~~~
shurcooL
I understand the problem, I'm thinking how to best solve it.

FWIW, the markdown files for all chapters in that book you've linked do not
contain an extra newline at the end; there's only one (just like markdownfmt
leaves it).

What about using something like cat, except one that inserts a newline between
all the files it concatenates? That way the .md files can remain as they are.

~~~
heinrich5991
You could also terminate each paragraph with a double-newline, instead of
using that to separate them. That would fix the problem.

------
gte910h
Can/has someone do this for Objective C? Clang-Format doesn't do it like Apple
and most programmers do, and nothing else comes close that I've seen.

------
NateDad
This is awesome. fmt all the things!

