Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/schmidt/literate_maruku

Literate Maruku is a literate programming libary for Ruby based on the Markdown libary Maruku.
https://github.com/schmidt/literate_maruku

hacktoberfest literate-programming markdown ruby

Last synced: 30 days ago
JSON representation

Literate Maruku is a literate programming libary for Ruby based on the Markdown libary Maruku.

Awesome Lists containing this project

README 

        
= Literate Maruku



Literate Maruku is a literate programming libary for ruby based on the markdown

libary maruku. This is basically what the name say, isn't it?



== The Basics



There are two possible accesses to the libary. A programming API and a command

line interface. The first may be used to write better documented tests,

for example. Just write a little bit of code in your test_helper and call

Literate Maruku there and your markdown formatted tests will be executed.



The command line interface may the be used inside of a rake task, e.g. to

generate some html files out of your test files demonstrating their usage.

We have used this approach in ContextR, so have a look there to get some input.



== Demonstration of Use



=== The Markdown Syntax



Literate Maruku simply extends the functionality of Maruku and adds some

methods to make standard use cases easier. You may find detailed information

about maruku at {their project page}[http://maruku.rubyforge.org/]. They added

some nice features to {Markdown

formatting}[http://daringfireball.net/projects/markdown/syntax], esp. the {meta

data syntax}[http://maruku.rubyforge.org/proposal.html] which made implementing

literate maruku a charm.



Wanna see examples? Okay, here they are:



==== Markdown



  This is a normal paragraph, followed by a plain old code block



      literate_maruku == maruku + ruby



  And the following code block will not only be rendered, but also executed.



      def echo_block(string)

        (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")

      end

  {: execute}



  And, finally, the following block will be executed and its output will be

  rendered as well.



      echo_block("hallo")

  {: execute attach_output}



==== HTML



This is a normal paragraph, followed by a plain old code block



  literate_maruku == maruku + ruby



And the following code block will not only be rendered, but also executed.



  def echo_block(string)

    (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")

  end



And, finally, the following block will be executed and its output will be

rendered as well.



  echo_block("hallo")

  >> "hello ... hell ... hel ... he ... h"



== The Command Line Interface



Simply call literate_maruku filename.mkd to load your markdown

formatted ruby files. This will execute the code but not generate any output.

It basically works like a simpe ruby filename.rb call, but without all

the command line parameters the +ruby+ command supports.



If you like to generate some html files, append an additional parameter, which

tells literate_maruku where to put the output.

literate_maruku --output_path=test filename.mkd would file the output

of filename.mkd to test/filename.html. That's all, folks.



== The Programming Interface



To use Literate Maruku in your own special way simply use the

LiterateMaruku#require method.



  require 'literate_maruku'



  LiterateMaruku.require('filename.mkd') # or

  LiterateMaruku.require('filename.mkd', :output => "test")



These will have the same result as the command line examples.



If you are unhappy with these little possibilities, no problem: You may still

use the standard maruku interface to do with your markdown string, what you like

after require'ing literate_maruku the maruku code base is extended for the

literate programming style.



== Installing & Compatibility



  gem install literate_maruku



Literate Maruku is currently only tested and known to work with



* Ruby 2.7, 3.0, 3.1



== Additional Resources



* {Project's website}[http://github.com/schmidt/literate_maruku/]

* {Introductory Talk about literate_maruku}[http://www.slideshare.net/schmidt/literate-maruku] (contains outdated URLs)

* {API doc}[http://rdoc.info/projects/schmidt/literate_maruku]

* {Build Status on GitHub Actions}[https://github.com/schmidt/literate_maruku/actions]



== How to submit patches



In order to submit patches, please fork the repository on GitHub, add your

patches to your own copy and send a "Pull Request" afterwards. I will then try

to add your submissions as soon as possible. Patches containing corresponding

tests are always welcome.



Bug reports or general feature requests should be added using GitHub Issues.



== License



This code is free to use under the terms of the MIT license.



  :include: License.txt