5 ms·

I've been starting to suffer from Markdown fatigue and investigating tools that support RST or asciidoc. I wonder if this system might support those tools in th

• pspeter3 9y ago
  Any reasons for the markdown fatigue?
  • geraldbauer 9y ago
    I've started work on an evolved markdown version called text with instructions (.texti) [1]. Anyways, what's broken in markdown? The image links are ugly e.g. . Why not {{pic.gif}}? Almost everybody incl. Wikipedia markup is using = for headings e.g. =Heading 1=. Why not also in Markdown? Another good reason is that # is the "universal" comment marker in the unix world. If you mix and match yaml front matter / back matter (meta data) with comments - why not use the same comments? Did you know - there are no comments in markdown. And so on and so on. It's time to fix (evolve) markdown. Cheers. [1] More at -> https://texti.github.io https://texti.github.io
  • drhayes9 9y ago
    Most of Markdown is great for me and feels natural. Headings, bold, italics, lists -- those are all great. Examples that don't feel natural are image syntax, dropping down to HTML for unsupported features (pre-supposes output format), emphasis on presentation vs. semantics, the various flavors of writing tables, etc. How do I write an index? A table of contents? Any way to differentiate a footnote or an aside from a basic link? YAML front matter is a great ad hoc standard for including metadata about a document within the document. It would be great if the various flavors of Markdown standardized on that, too.
  • WorldMaker 9y ago
    Having used a lot of markdown and reStructuredText, I can see the arguments that the lack of common standards in markdown is a huge pain. There's still a lot of variety between markdown implementations and while Common Mark and open GFM standards are helping to a point, you still can't always count on a markdown engine to have things as basic as definition list support or HTML anchor support (linkable ids for sub-headings), and there are still some weird subtle implementation differences in those things. There's also a lot to be said about the way that reStructuredText provides standard plugin spaces in the markup. While it may look over verbose at first glance, it is a great thing when you start to pick up that a lot of reStructuredText is based on the same plugin markup and there's a consistent way to work with new plugins. Something like that could be hugely useful to Markdown, and probably could have stymied some of the complications in standardizing things like Common Mark and GFM had that consideration been baked in from early on.
• dsr_ 9y ago
  You could use Pelican (getpelican.com) -- it's an SSG that supports Markdown and RST and asciidoc and is generally extensible.
  • arfar 9y ago
    Pelican is great for blogs. I don't know that I'd suggest it for a "Knowledgebase".
• jldugger 9y ago
  The readthedocs engine is RST friendly. Personally I prefer documentation that's easy to write and RST is not that.
  • drhayes9 9y ago
    I admit, I haven't tried to write a lot of RST or asciidoc beyond playing around with it. And it's a good point -- docs that are hard to write don't get written.
• mcone 9y ago
  Asciidoctor has a plugin for Jekyll you might be interested in: https://github.com/asciidoctor/jekyll-asciidoc https://github.com/asciidoctor/jekyll-asciidoc
• type0 9y ago
  I wonder also, gitbook-cli supports both md and adoc. Asciidoctor is easier to write and you don't have to use its advanced features for it to become superior to Markdown. == What is easier to write? <!-- md comment --> or // adoc comment == What is easier to write? <a href="http://foo.com"></a> http://foo.com"></a> or image:adoc-foo.jpg[link="http://foo.com" http://foo.com"] == What is easier to write? 1. first md - no auto numbering 2. second md - no auto numbering 3. third md - no auto numbering or . first adoc - auto numbering . second adoc - auto numbering . third adoc - auto numbering What is easier to write? [Get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/my-md-file.pdf) or link:{ctx_path}/assets/my-adoc-file.pdf[Get the PDF]
  • dgfgfdagasdfgfa 9y ago
    > . first adoc - auto numbering That looks like a bullet to me. How do you differentiate unordered and ordered lists? Also, markdown auto-numbers too, so you can just prefix every item with `1` if you'd like.
    • type0 9y ago
      > so you can just prefix every item with `1` if you'd like. oh, didn't knew that, use asterisks instead of dots is for bulletspoints in asciidoc. For unordered lists use more than one asterisk (HN breaks my example here), look at this example http://www.methods.co.nz/asciidoc/chunked/ch17.html http://www.methods.co.nz/asciidoc/chunked/ch17.html if you mean Implicit numbering You could also do: [start=5] . nr-5 . nr-6 . nr-7