I run a blog using Jekyll, and thought I'd settle with Redcarpet markdown interpreter as it's developed and used by GitHub.
Well, I just happened to come across a bug, went to checkout the issues, and found this.
Maintainer says, "As you probably have noticed (har har har har) I don't have time to maintain Redcarpet anymore. It's not a priority for me (I find Markdown thoroughly boring) and it's not a priority for GitHub, because we no longer use it in production."
So...
Is there a good Ruby markdown interpreter (i.e. actively developed, with sane syntax) that I can use with Jekyll (& pygments)?
Even better, a markdown interpreter with syntax similar to (or at least close to) GitHub Flavored Markdown?
https://github.com/vmg/redcarpet Redcarpet is very actively developed and was updated about 8 hours ago (at the time of this writing.)
For "flavoring" your Markdown: https://rubygems.org/gems/github-markdown
To convert Markdown to HTML:
GitHub::Markdown.render_gfm("# Header")
To render within Rails:
GitHub::Markdown.render_gfm("# Header").html_safe
Want syntax highlighting?
https://github.com/simplabs/highlight
https://alphahydrae.com/2013/01/markdown-views-in-rails/
Cheers!
Related
I am trying to automate documentation using markdown compatible wiki without having a separate server.
I have ruby code with yard compatible documentation. If I run
yard doc, it generates html files in ./doc directory.
Would it be possible to generate .md files from the code using yard? So that I can simply add these files to GitLab or GitHub wiki or other markdown supported wiki?
Sorry if the question is repeated.
Stumbled on this question doing my initial research, but haven't found an answer here. It may sound strange, that some people want to convert documentation no to html, but to markdown instead.
But there are plenty of software that can't render HTML, but works with markdown.
I have developed rdoc plugin to do that.
https://github.com/skatkov/rdoc-markdown
Standard ruby on rails project has README.rdoc.
Many github rails projects have README.md.
What is the difference?
Answer fragment from another deleted Stack Overflow question by kiddorails:
RDoc is a fantastic tool which enables the automatic generation of formatted HTML containing our documented code.
For example, most of gems on RubyGems fetch documentation and compiles them to give the resultant rdoc.
If your project doesn't have README.md, GitHub may parse README.rdoc to display details. If it has both, it will use README.md, silently ignoring rdoc. I usually have both, README.md for Github, and README.rdoc for RDoc documentation on RubyGems.
RDoc - is a RubyGem which produces HTML and command-line documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying documentation from the command-line.
Digging Deeper Rdoc
Markdown also known as md is a plain text formatting syntax5 designed so that it can optionally be converted to HTML using a tool by the same name. Markdown is popularly used as format for readme files, or for writing messages in online discussion forums, or in text editors for the quick creation of rich text documents.
Github's Markdown
Github's Markdown basics
RDoc is a markup language. Markdown is a different markup language. HTML is yet another markup language. Any of those can be used to markup text, and all of those are supported by various code-browsing tools including but not limited to GitHub.
I have a problem :0
At my place of work we have two wiki systems and I have been charged with finding a way of migrating from a MediaWiki to a redmine wiki -- only problem is they use different markup languages (WikiText vs Textile) and a possible solution (Pandoc) only goes the other way :0 Any suggestions on how to do this would be greatly appreciated!!!
The MediaWiki to Redmine Migration Tool (MRMT) has just been released.
It migrates the whole history with the correct user assigned to each revision.
Besides a basic Pandoc translation it also adds some helpful replacements that will very likely be necessary in any migration of that kind.
The development version of pandoc now has a mediawiki reader. It doesn't support all of mediawiki syntax (e.g. templates), and it is not very well tested, but you could try it out.
You would need to install the development version of pandoc from source to do this. Install the Haskell Platform, then follow the instructions here.
(These instructions assume a *nix build environment.)
You will probably want to use some scripting to adjust the result, e.g. making links with title "wikilink" into proper redmine wikilinks. It is easiest to do this at the level of the pandoc AST, rather than in the textile result. The document on Scripting with pandoc on the pandoc website may be of help here.
Another approach is to scrape the HTML your redmine wiki produces, and use pandoc to convert that to textile. This approach typically requires a lot of preprocessing and postprocessing, though.
You could also try using one of the various alternative mediawiki parsers, producing HTML or DocBook and converting that to textile using pandoc.
I saw this related question about publishing toolchain but I know many people did lot of work to produce publishing toolchains recently.
One great example I found is this project from akosma.
Avdi Grimm shared his work with org-mode in this project
I know there are (should be) many others.
What I'm looking for, is a publishing toolchain with
asciidoc / markdown / textile / org-mode or latex input. I don't want xml input
pdf AND html output, epub output is not a requirement for me.
What I can
author templates in latex / html / css / js. again, no xml.
read and write ruby and shell scripts
Take a look at asciidoc, this is what O'Reilly has started using and it is a refreshing break from DocBook. I use asciidoc, the tools and support leaves a little to be desired, but there are people working to create better alternatives (that don't involve Python and the existing Docbook pipeline).
Check out this: https://github.com/runemadsen/asciidoc
EDIT 1/6/13: You also really need to check out AsciiDoctor. Dan Allen from RedHat has been spending a lot of time on this particular package and Ryan Waldron. I expect great things from AsciiDoctor as it is starting to emerge as a foundation for a bunch of important AsciiDoc documentation efforts.
There are many libraries for transforming markups like reStructuredText and markdown to HTML. I have some users who are familiar with the markup used in Atlassian's Confluence wiki product, which is unfortunately proprietary -- is there any open source compiler for the confluence wiki markup format, or possibly something that would transform it to an intermediate format?
I think Confluence uses the Textile markup format. I have used over the last few years a rails application that used the gem RedCloth to do the transformation, and I could switch between the 2 formats. I never checked if it is complete interchangeable, however.
You could check for yourself if it is sufficient at Try RedCloth.