Source2MD: Markdown generator from source code

Logic

Divide the source code into paragraphs using blank lines as separations.
Remove comments from the comment blocks.
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(<<~EOS).to_md
  hello = -> {
    "Hello, world!"
  }

  #+partial_code_name: (name)
  #+partial_code_lang: (ruby)
  hello.call
EOS

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

hello.call

Source block with many lines

puts Source2MD::Section.new(<<~EOS).to_md
  #+BEGIN_SRC
  hello = -> {
    "Hello, world!"
  }

  hello.call
  #+END_SRC
EOS

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

hello.call

Hide paragraph

puts Source2MD::Section.new(<<~EOS).to_md
  #+hidden: true
  p "This paragraph is not displayed"
EOS

puts Source2MD::Section.new(<<~EOS).to_md
  #+BEGIN_SRC hidden!
  p "This paragraph is not displayed"
  #+END_SRC
EOS

Code include

Insert inside the code block.

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

puts Source2MD::Section.new(<<~EOS).to_md
  #+code_include: /tmp/hello.html

  #+code_include: /tmp/hello.html xml:OUTPUT
EOS

```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(<<~EOS).to_md
  #+raw_include: /tmp/hello.html
EOS

<p>Hello</p>

Title

No number limit.

puts Source2MD::Section.new(<<~EOS).to_md
  #+title1: Title Level 1

  #+title2: Title Level 2

  #+title3: Title Level 3
EOS

# Title Level 1 #

## Title Level 2 ##

### Title Level 3 ###

Org-mode table style

puts Source2MD::Section.new(<<~EOS).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                           |
  # |------------+-------+--------------------------------------------|
EOS

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

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(<<~EOS).to_md
  #+name: String#size
  #+desc: Return the number of characters
  #+comment: Comments about size
  "abc".size     # => 3

  #+name: String#reverse
  #+desc: reverse the sequence of characters
  #+comment: Comments about reverse
  "abc".reverse  # => "cba"
EOS

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(<<~EOS).to_md
  #+warn: this is warning message

  #+alert: this is alert message
EOS

:::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(<<~EOS).to_md
  # Lorem ipsum dolor sit amet, consectetur adipisicing elit,
  # sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
EOS

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(<<~EOS).to_md
  #+squish: true
  # Lorem ipsum dolor sit amet, consectetur adipisicing elit,
  # sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
EOS

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

Squish Text

Single spaces for line breaks and consecutive spaces.

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

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

Hankaku Kana

JISX0208 Katakana to JISX0201 Katakana.

puts Source2MD::Section.new(<<~EOS).to_md
  #+hankaku_kana: true
  # ｱア
EOS

ｱｱ

Parse include

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

File.write("/tmp/hello.rb", <<~EOS)
# foo
EOS

puts Source2MD::Section.new(<<~EOS).to_md
  #+parse_include: /tmp/hello.rb
EOS

foo

Eval

Function for changing internal variables

puts Source2MD::Section.new(<<~EOS).to_md
  #+eval: Source2MD.lang_default = "shell"
EOS

source2md

Development

Runtime