According to github/murkup's README, it's available to add comstomed markup language on Github.
https://github.com/github/markup
Markdown is really clumsy to use for simple projects. I just want a markup language which supports "bold", 'inline code', 'code blocks', 'links'. No need to add blanks to change line, just be simple like code. I think it already enough in most cases. So here's my code in CoffeeScript.
https://gist.github.com/3712310
I haven't learn Ruby yet. So I don't kown how to debug my language before I push it to Github, since there's not a detailed guide for beginner. Could anyone help me?
By the way, does Github accepts such a language?
The answer is in the README:
If your markup is in a language other than Ruby, drop a translator script in lib/github/commands which accepts input on STDIN and returns HTML on STDOUT. See rest2html for an example.
I encourage you to take another look at the other supported languages. Just because your file is in Markdown doesn't mean you have to use all of the features. Textile is a nice alternative, but so are all of the syntaxes supported by markup.
Think of tool and editor support in your language, and why users would want to use it. What does it bring to the table? What does it solve? It looks identical to Markdown, minus the features. You will likely need to sell your specialized markup language with one user in your pull request.
Related
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.
Ruby has a few good document generators like Yard, rDoc, even Glyph. The thing is that Sphinx does websites, PDF's, epub, LaTex...etc. It does all these things in restructuredtext.
Is there an alternative to this in the Ruby world? Maybe a combination of programs? If I could use Markdown as well that would be even better.
Since version 1.0, Sphinx has had a concept of "domains" which are ways of marking up code entities (like method calls, objects, functions, whatever) from lannguages other than Python and/or C.
There is a ruby domain, so you could just use Sphinx itself. The only thing you would be missing (I think) is Sphinx's ability to create documentation from source automatically using the autodoc extension, which works specifically on Python code.
If you want to use Markdown, you might check out JDoc, which is a very simple, Ruby-based documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice, and it supports:
Markdown or Textile
syntax highlighting
easy internal links
a hierarchical documentation structure (useful for large projects)
customizable styling and structure (but it looks nice out of the box, too)
It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.
To see it in action, check out wpmvc.org.
Another couple of options would be to use Middleman which is a static site generator that accepts either Kramdown or Markdown as input.
There are also frameworks that are designed specifically for technical documentation that use Middleman (both of which are on GitHub) including lord/slate and pnerger/dpslate (the later is a fork of the former and provides some enhancements that were not appropriate for pulling). The Slate format provides a format for documentation that includes many of the features of Sphinx with some additional enhancements. It features a three-pane view of a document which includes an automatically generated Table of Contents, a Main center body, and then sample code panel to the right. Like Sphinx the sample code has syntax highlighting.
I need to call some helpers from a Markdown view. Is this somehow a good practice and is generally supported on popular ruby-based Markdown parsers?
No, it isn't. Markdown is a standardized, text-focused, cross-language format and the most of Markdown parsers offers support for the standard syntax.
However, platforms that need advanced features, such as wiki and GitHub, adds custom features. Common features, are tags to generate page TOC based on the document structure.
AFAIK, not BlueCloth nor RDiscount offers built-in support for extensions. You would have to code them yourself before passing the markdown text to processor.
Extending the class to handle new tags or syntax is not a bad idea, but eval'ing inline ruby code from a possibly untrusted source is an absolutely horrible idea!
I'm looking for a general purpose syntax highlighting library, to output to html.
It's for use within a ruby app, so a ruby library would be good, but an excellent utility which can be piped in and out of would do
Also needs to guess the appropriate language to highlightsy by itself
HTML/CSS/JavaScript based syntax highlighter solutions are the most popular and work well with different server technologies including Ruby.
SyntaxHighlighter (RECOMMENDED) is here to help a developer/coder to post code snippets online with ease and have it look pretty. It's 100% Java Script based and it doesn't care what you have on your server.
Syntax highlighting library for various languages at Rubyforge.org. Has built-in support for converting source code to syntax-highlighted HTML.
SyntaxHighlighter for WordPress. It allows you to easily post syntax highlighted code all without losing its formatting or making an manual changes.
Prettify. A Javascript module and CSS file that allows syntax highlighting of source code snippets in an html page.
GeSHi - Generic Syntax Highlighter. GeSHi started as an idea to create a generic syntax highlighter for the phpBB forum system, but has been generalised to this project. GeSHi aims to be a simple but powerful highlighting class, with the following goals: (1) Support for a wide range of popular languages (2) Easy to add a new language for highlighting (3) Highly customisable output formats
JUSH is a syntax highlighting component written in JavaScript. It highlights HTML, CSS, JS, PHP and SQL code embedded into each other. Beside syntax highlighting, it provides links to the documentation for all supported languages.
SyntaxHighlighter for Windows Live Writer at CodePlex.com (just in case :)
And here a few blog posts on the subject:
Syntax Highlighting for Ruby Made Very Easy
Syntax highlighting in Ruby
Have you looked at Google's syntax highlighter? I believe SO uses it?
http://code.google.com/p/syntaxhighlighter/
Edit: Actually I believe it is Prettify:
http://code.google.com/p/google-code-prettify/
Some options are:
Syntax - Its really broad, but I think it has some licensing concerns (Syntax is GPL)
Coderay - I use this on my blog, it's pretty limited, but is functional
Ultraviolet which support a ton of languages (anything that textmate can do)
If you are willing to bridge into Python there is Pygments, which supports a ton of languages
Try rouge. It's pure ruby, compatible with pygments, and actively developed.
You might want to take a look at Colorer. It doesn't seem to have bindings for Ruby, but there are for Perl and PHP, maybe one would be able to hack a binding together for Ruby on that basis.
Scintilla can be used with C++ code. I don't know about is there a way to use C++ applications in Ruby.
Is there a utility that will generate html or css for blocks of code (.net c#) when you post it on a website?
I have seen several websites with very nicely formatted code and I dont believe they do this manually.
Google prettify -
http://code.google.com/p/google-code-prettify/
I prefer Syntax Highlighter implementations (I'm using Wordpress plugin implementation for my blog).
Advantages
It is based on JavaScript and does
not care about what you have on the
server.
Posts with this formatting display
properly on different RSS feeds and
can be copied to clipboard.
It is trivial to extend syntax
rules. I'm using that to highlight
custom operators in Boo-based DSL (see sample post)
Multiple languages are supported
out-of-the-box
(source: googlecode.com)
You can get JavaScript syntax-highlighting scripts, such as this one by Dean Edwards.
This is also a jQuery version apparently based on it which looks good.
CopySourceAsHtml is an add-in for Microsoft Visual Studio 2005 that allows you to copy source code, syntax highlighting, and line numbers as HTML.
http://copysourceashtml.codeplex.com
It's highly configurable, and works much better than the download page would make you expect! Don't know if there is something similar for VS 2008
If you don't have the ability to add the google prettifier CSS reference, this would be a better way to go, as what you get is a complete HTML with the required style. I use it all the time on our developers wiki, and loving it.
An even better solution, if you don't want to bother installing anything, is to just use the little web app I wrote called BlogTrog CodeWindow:
http://www.blogtrog.com
It's easy to use. Just paste your code and embed the results.