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(<<~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

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