5 ms·

Show HN: Ditto – Markdown documentation system

41 points by chutsu 12y ago

tomasien 12y ago
This is great! I'm building our docs using Aglio right now and it's great - this seems similar but with some interesting differences. Really good to see more options out there!
lulle 12y ago
I don't understand all the fuzz about Markdown. Doesn't people realize that it exists other much more powerful lightweight markup languages like AsciiDoc?
- morganherlocker 12y ago
  It looks powerful, but with a much steeper learning curve for non technical users[1]. I could see the nested list support being great for outlines, and tables look a lot more robust than in markdown, but I do not know if it is worth the tradeoffs of going against markdown's ubiquity. [1] http://powerman.name/doc/asciidoc http://powerman.name/doc/asciidoc
- JoeAnzalone 12y ago
  I've never heard of AsciiDoc, but I'd say the biggest advantage that Markdown has is its ubiquity. It's used by GitHub, StackOverflow, Reddit, and even Tumblr has an option for it.
  - Turing_Machine 12y ago
    Also the fact that there are multiple (and good) client-side Markdown libraries while stuff like AsciiDoc generally requires server-side rendering (and the associated server load and round-trip penalties). Unless I'm missing it, there's no pure client-side AsciiDoc?
    - chutsu 12y ago
      [1] seems to be an AsciiDoc render on client-side, though have no idea if it's any good though... [1]: http://asciidoctor.org/news/2013/05/21/asciidoctor-js-render-asciidoc-in-the-browser/ http://asciidoctor.org/news/2013/05/21/asciidoctor-js-render...
      - Turing_Machine 12y ago
        Yeah, hard to say without a live demo. Also, downloading an entire Ruby interpreter in JS seems a little on the heavy side. If you were going to go that route, might as well use texlive.js and get a full-blown LaTeX system. :-) Cool nonetheless.
  - lulle 12y ago
    I think ubiquity comes with knowledge, if there exists superior tools, people tend to use them eventually. I know that GitHub supports AsciiDoc already, one would hope that the other ones become enlightened!
- chutsu 12y ago
  It was simply the plain-text format I am currently using, I'm sure I can add in compatibility for AsciiDoc no probs. Just a matter of adding in an AsciiDoc renderer. :)
ryanSrich 12y ago
Almost looks like Slate Docs[1]. 1. https://github.com/tripit/slate https://github.com/tripit/slate
james2vegas 12y ago
Yeah, because there aren't any documentation systems called mdoc already, at all. http://man7.org/linux/man-pages/man7/mdoc.7.html http://man7.org/linux/man-pages/man7/mdoc.7.html http://www.mono-project.com/Mdoc http://www.mono-project.com/Mdoc
- clarry 12y ago
  Related: http://mdocml.bsd.lv/ http://mdocml.bsd.lv/
- chutsu 12y ago
  alright, no need to be a smart arse, I wasn't aware of those tools.
  - dang 12y ago
    Yes, that comment was uncivil and broke the HN guidelines. It should have just neutrally pointed out the other tools. This reply also breaks the guidelines. Please don't reply to incivility with incivility on HN. It's hard not to, but doing so only makes things worse.
    - chutsu 12y ago
      Sorry, got it.
chutsu 12y ago
Sorry guys I had to change the name because mdoc is already used by other programs. I changed it to `ditto`. New Link: http://chutsu.github.io/ditto/ http://chutsu.github.io/ditto/
- skue 12y ago
  I assume you searched and discovered that ditto is also a BSD command for copying files, which is included on all Macs?[1] This conflict may not be as confusing as the original name. I gather from the docs that you never invoke your version of ditto from the command line? [1]: https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/ditto.1.html https://developer.apple.com/library/mac/documentation/Darwin...
  - chutsu 12y ago
    ... Atleast it doesn't clash with the established documentation system mdoc.
- dang 12y ago
  Ok, we've edited the title and url of the post to match.
johnohara 12y ago
I've used both Multi-Markdown and Pandoc in past projects so I was intrigued by the associated live demo. Was it generated using Ditto?
- chutsu 12y ago
  Yep, essentially ditto. :) I would like to add that nothing is technically generated* they. The markdown files are rendered on the fly using a Javascript Markdown parser. The layout is simply HTML5 and CSS, with a dash of jQuery to make the buttons work.
dangoor 12y ago
Does Google crawl this documentation? I know they have some JS support in their crawler, but is it enough that it would actually index a docsite built with this tool?
- chutsu 12y ago
  Not sure Google would be able to index the docs, since they are in markdown format. But I'm not an expert in how Google index the pages.
  - Ben-G 12y ago
    No, google doesn't. I've built a similar solution for the Cocos2D documentation that is going to be released soon. I've added a php server component to deliver HTML snapshots to google crawlers for that purpose.
    - deleted 12y ago
      [deleted]
  - Ben-G 12y ago
    I have now released my similar documentation system that supports SEO: https://github.com/Ben-G/Lightdoc https://github.com/Ben-G/Lightdoc

41 points by chutsu 12y ago

This is great! I'm building our docs using Aglio right now and it's great - this seems similar but with some interesting differences. Really good to see more options out there!

lulle 12y ago

I don't understand all the fuzz about Markdown. Doesn't people realize that it exists other much more powerful lightweight markup languages like AsciiDoc?

morganherlocker 12y ago
It looks powerful, but with a much steeper learning curve for non technical users[1]. I could see the nested list support being great for outlines, and tables look a lot more robust than in markdown, but I do not know if it is worth the tradeoffs of going against markdown's ubiquity. [1] http://powerman.name/doc/asciidoc http://powerman.name/doc/asciidoc
JoeAnzalone 12y ago
I've never heard of AsciiDoc, but I'd say the biggest advantage that Markdown has is its ubiquity. It's used by GitHub, StackOverflow, Reddit, and even Tumblr has an option for it.
- Turing_Machine 12y ago
  Also the fact that there are multiple (and good) client-side Markdown libraries while stuff like AsciiDoc generally requires server-side rendering (and the associated server load and round-trip penalties). Unless I'm missing it, there's no pure client-side AsciiDoc?
  - chutsu 12y ago
    [1] seems to be an AsciiDoc render on client-side, though have no idea if it's any good though... [1]: http://asciidoctor.org/news/2013/05/21/asciidoctor-js-render-asciidoc-in-the-browser/ http://asciidoctor.org/news/2013/05/21/asciidoctor-js-render...
    - Turing_Machine 12y ago
      Yeah, hard to say without a live demo. Also, downloading an entire Ruby interpreter in JS seems a little on the heavy side. If you were going to go that route, might as well use texlive.js and get a full-blown LaTeX system. :-) Cool nonetheless.
- lulle 12y ago
  I think ubiquity comes with knowledge, if there exists superior tools, people tend to use them eventually. I know that GitHub supports AsciiDoc already, one would hope that the other ones become enlightened!
chutsu 12y ago
It was simply the plain-text format I am currently using, I'm sure I can add in compatibility for AsciiDoc no probs. Just a matter of adding in an AsciiDoc renderer. :)

ryanSrich 12y ago

Almost looks like Slate Docs[1]. 1. https://github.com/tripit/slate https://github.com/tripit/slate

james2vegas 12y ago

Yeah, because there aren't any documentation systems called mdoc already, at all. http://man7.org/linux/man-pages/man7/mdoc.7.html http://man7.org/linux/man-pages/man7/mdoc.7.html http://www.mono-project.com/Mdoc http://www.mono-project.com/Mdoc

clarry 12y ago
Related: http://mdocml.bsd.lv/ http://mdocml.bsd.lv/
chutsu 12y ago
alright, no need to be a smart arse, I wasn't aware of those tools.
- dang 12y ago
  Yes, that comment was uncivil and broke the HN guidelines. It should have just neutrally pointed out the other tools. This reply also breaks the guidelines. Please don't reply to incivility with incivility on HN. It's hard not to, but doing so only makes things worse.
  - chutsu 12y ago
    Sorry, got it.

chutsu 12y ago

Sorry guys I had to change the name because mdoc is already used by other programs. I changed it to `ditto`. New Link: http://chutsu.github.io/ditto/ http://chutsu.github.io/ditto/

skue 12y ago
I assume you searched and discovered that ditto is also a BSD command for copying files, which is included on all Macs?[1] This conflict may not be as confusing as the original name. I gather from the docs that you never invoke your version of ditto from the command line? [1]: https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/ditto.1.html https://developer.apple.com/library/mac/documentation/Darwin...
- chutsu 12y ago
  ... Atleast it doesn't clash with the established documentation system mdoc.
dang 12y ago
Ok, we've edited the title and url of the post to match.

johnohara 12y ago

I've used both Multi-Markdown and Pandoc in past projects so I was intrigued by the associated live demo. Was it generated using Ditto?

chutsu 12y ago
Yep, essentially ditto. :) I would like to add that nothing is technically generated* they. The markdown files are rendered on the fly using a Javascript Markdown parser. The layout is simply HTML5 and CSS, with a dash of jQuery to make the buttons work.

dangoor 12y ago

Does Google crawl this documentation? I know they have some JS support in their crawler, but is it enough that it would actually index a docsite built with this tool?

chutsu 12y ago
Not sure Google would be able to index the docs, since they are in markdown format. But I'm not an expert in how Google index the pages.
- Ben-G 12y ago
  No, google doesn't. I've built a similar solution for the Cocos2D documentation that is going to be released soon. I've added a php server component to deliver HTML snapshots to google crawlers for that purpose.
  - deleted 12y ago
    [deleted]
- Ben-G 12y ago
  I have now released my similar documentation system that supports SEO: https://github.com/Ben-G/Lightdoc https://github.com/Ben-G/Lightdoc