Source2MD: Markdown generator from source code

Logic

1. Divide the source code into paragraphs using blank lines as separations.
2. Remove comments from the comment blocks.
3. Include the code within the code block.

Install

$ gem i source2md

CLI

$ source2md generate -o README.md README.rb

Rules

Code snippet

Separated by blank lines.

puts Source2MD::Section.new("hello = -> {\n  \"Hello, world!\"\n}\n\nhello.call\n").to_md

hello = -> {
  "Hello, world!"
}

hello.call

Source block with many lines

puts Source2MD::Section.new("#+BEGIN_SRC\nhello = -> {\n  \"Hello, world!\"\n}\n\nhello.call\n#+END_SRC\n").to_md

hello = -> {
  "Hello, world!"
}

hello.call

Hide paragraph

puts Source2MD::Section.new("#+hidden: true\np \"This paragraph is not displayed\"\n").to_md

Code include

Insert inside the code block.

File.write("/tmp/hello.html", "<p>Hello</p>")

puts Source2MD::Section.new("#+code_include: /tmp/hello.html\n\n#+code_include: /tmp/hello.html xml:OUTPUT\n").to_md

```html:hello.html
<p>Hello</p>
```

```xml:OUTPUT
<p>Hello</p>
```

Raw include

File.write("/tmp/hello.html", "<p>Hello</p>")

puts Source2MD::Section.new("#+raw_include: /tmp/hello.html\n").to_md

<p>Hello</p>

Title

No number limit.

puts Source2MD::Section.new("#+title1: Title Level 1\n\n#+title2: Title Level 2\n\n#+title3: Title Level 3\n").to_md

# Title Level 1 #

## Title Level 2 ##

### Title Level 3 ###

Markdown style title

The condition is that there are the same number of sharps on the back.

puts Source2MD::Section.new("# Title Level 1 #\n\n## Title Level 2 ##\n\n### Title Level 3 ###\n").to_md

# Title Level 1 #

## Title Level 2 ##

### Title Level 3 ###

Org-mode table style

puts Source2MD::Section.new("# |------------+-------+--------------------------------------------|\n# | Language   | Birth | Creator                                    |\n# |------------+-------+--------------------------------------------|\n# | Lisp       |  1958 | John McCarthy                              |\n# | Fortran    |  1957 | John Backus                                |\n# | COBOL      |  1959 | Grace Hopper and team                      |\n# | Algol      |  1958 | International group of computer scientists |\n# | BASIC      |  1964 | John G. Kemeny and Thomas E. Kurtz         |\n# | Pascal     |  1970 | Niklaus Wirth                              |\n# | C          |  1972 | Dennis Ritchie                             |\n# | Prolog     |  1972 | Alain Colmerauer, Robert Kowalski          |\n# | C++        |  1983 | Bjarne Stroustrup                          |\n# | Python     |  1989 | Guido van Rossum                           |\n# |------------+-------+--------------------------------------------|\n").to_md

Language	Birth	Creator
Lisp	1958	John McCarthy
Fortran	1957	John Backus
COBOL	1959	Grace Hopper and team
Algol	1958	International group of computer scientists
BASIC	1964	John G. Kemeny and Thomas E. Kurtz
Pascal	1970	Niklaus Wirth
C	1972	Dennis Ritchie
Prolog	1972	Alain Colmerauer, Robert Kowalski
C++	1983	Bjarne Stroustrup
Python	1989	Guido van Rossum

Explain method simply

puts Source2MD::Section.new("#+name: String#size\n#+desc: Return the number of characters\n#+comment: Comments about size\n\"abc\".size     # => 3\n\n#+name: String#reverse\n#+desc: reverse the sequence of characters\n#+comment: Comments about reverse\n\"abc\".reverse  # => \"cba\"\n").to_md

String#size

Return the number of characters

"abc".size  # => 3

Comments about size

String#reverse

reverse the sequence of characters

"abc".reverse  # => "cba"

Comments about reverse

Warning and Alert message

Exclusive to Zenn

puts Source2MD::Section.new("#+warn: this is warning message\n\n#+alert: this is alert message\n").to_md

:::message
this is warning message
:::

:::message alert
this is alert message
:::

Raw Text

If no rule applies and the text begins with #, remove the #.

puts Source2MD::Section.new("# Lorem ipsum dolor sit amet, consectetur adipisicing elit,\n# sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n").to_md

Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Oneline Text

Using this option allows you to split a line regardless of the markdown library.

puts Source2MD::Section.new("#+oneline: true\n# Lorem ipsum dolor sit amet, consectetur adipisicing elit,\n# sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n").to_md

Lorem ipsum dolor sit amet, consectetur adipisicing elit,sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Parse include

Paste the results of processing other files with the same rules.

File.write("/tmp/hello.rb", "# foo\n")

puts Source2MD::Section.new("#+parse_include: /tmp/hello.rb\n").to_md

foo