The commondoc-markdown Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The commondoc-markdown Reference Manual

This is the commondoc-markdown Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:30:35 2022 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

CommonDoc-Markdown

This is a wrapper around 3BMD markdown parser which produces documents in CommonDoc format. Also, it is able to render CommonDoc documents into the Markdown.

It is a proof of the concept, but I'm already using it in the documentation builder 40ANTS-DOC.

Note. This library is not compatible with CommonMark yet.

Installation

This library available only at Ultralisp.org now. To install it using Quicklisp client, do:

(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)

(ql:quickload :commondoc-markdown)

Parsing Markdown to CommonDoc

CL-USER> (common-doc.format:parse-document
          (make-instance 'commondoc-markdown:markdown)
          "
# Hello World

* First item
* Second item
")
#<COMMON-DOC:SECTION title: Hello World, ref: NIL>

Writing CommonDoc to Markdown

Now we can render our document back to Markdown:

CL-USER> (common-doc.format:emit-to-string
          (make-instance 'commondoc-markdown:markdown)
          *document*)
"# Hello World

* First item

* Second item


"

API

variable commondoc-markdown/emitter:*generate-short-link-references* t

By default it is T, but you can bind it to NIL, to prevent short link references generation.

variable commondoc-markdown/emitter:*min-link-hash-length* 4

Minumum length of the hash for generated markdown links. This works only when *generate-short-link-references* variable is set to T.

variable commondoc-markdown/emitter:*emit-section-anchors* t

When this variable is T (default), emitter outputs a raw html <a name="some-id"></a> before each Markdown section.

Roadmap


[generated by 40ANTS-DOC]

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 commondoc-markdown

Author

Alexander Artemenko

Home Page

https://40ants.com/commondoc-markdown/

Source Control

(:git "https://github.com/40ants/commondoc-markdown")

Bug Tracker

https://github.com/40ants/commondoc-markdown/issues

License

Unlicense

Description

Converter from Markdown to CommonDoc.

Dependencies
Source

commondoc-markdown.asd (file)


Next: , Previous: , Up: Systems   [Contents][Index]

2.2 commondoc-markdown/emitter

Author

Alexander Artemenko

Home Page

https://40ants.com/commondoc-markdown/

Source Control

(:git "https://github.com/40ants/commondoc-markdown")

Bug Tracker

https://github.com/40ants/commondoc-markdown/issues

License

Unlicense

Dependencies
Source

commondoc-markdown.asd (file)

Component

file-type.lisp (file)


Next: , Previous: , Up: Systems   [Contents][Index]

2.3 commondoc-markdown/core

Author

Alexander Artemenko

Home Page

https://40ants.com/commondoc-markdown/

Source Control

(:git "https://github.com/40ants/commondoc-markdown")

Bug Tracker

https://github.com/40ants/commondoc-markdown/issues

License

Unlicense

Dependencies
Source

commondoc-markdown.asd (file)

Component

file-type.lisp (file)


Next: , Previous: , Up: Systems   [Contents][Index]

2.4 commondoc-markdown/addons

Author

Alexander Artemenko

Home Page

https://40ants.com/commondoc-markdown/

Source Control

(:git "https://github.com/40ants/commondoc-markdown")

Bug Tracker

https://github.com/40ants/commondoc-markdown/issues

License

Unlicense

Dependencies
Source

commondoc-markdown.asd (file)

Component

file-type.lisp (file)


Next: , Previous: , Up: Systems   [Contents][Index]

2.5 commondoc-markdown/raw-html

Author

Alexander Artemenko

Home Page

https://40ants.com/commondoc-markdown/

Source Control

(:git "https://github.com/40ants/commondoc-markdown")

Bug Tracker

https://github.com/40ants/commondoc-markdown/issues

License

Unlicense

Dependencies
Source

commondoc-markdown.asd (file)

Component

file-type.lisp (file)


Previous: , Up: Systems   [Contents][Index]

2.6 commondoc-markdown/format

Author

Alexander Artemenko

Home Page

https://40ants.com/commondoc-markdown/

Source Control

(:git "https://github.com/40ants/commondoc-markdown")

Bug Tracker

https://github.com/40ants/commondoc-markdown/issues

License

Unlicense

Source

commondoc-markdown.asd (file)

Component

file-type.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 commondoc-markdown.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/commondoc-markdown-20220331-git/commondoc-markdown.asd

Systems

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 commondoc-markdown/emitter/file-type.lisp

Parent

commondoc-markdown/emitter (system)

Location

emitter.lisp

Packages

commondoc-markdown/emitter

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 commondoc-markdown/core/file-type.lisp

Parent

commondoc-markdown/core (system)

Location

core.lisp

Packages

commondoc-markdown

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 commondoc-markdown/addons/file-type.lisp

Parent

commondoc-markdown/addons (system)

Location

addons.lisp

Packages

commondoc-markdown/addons

Internal Definitions

*strikethrough* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 commondoc-markdown/raw-html/file-type.lisp

Parent

commondoc-markdown/raw-html (system)

Location

raw-html.lisp

Packages

commondoc-markdown/raw-html

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.6 commondoc-markdown/format/file-type.lisp

Parent

commondoc-markdown/format (system)

Location

format.lisp

Packages

commondoc-markdown/format

Exported Definitions

markdown (class)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 commondoc-markdown/emitter

Source

file-type.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

4.2 commondoc-markdown

Source

file-type.lisp (file)

Nickname

commondoc-markdown/core

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

4.3 commondoc-markdown/addons

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

*strikethrough* (special variable)


Next: , Previous: , Up: Packages   [Contents][Index]

4.4 commondoc-markdown/raw-html

Source

file-type.lisp (file)

Use List

common-lisp

Exported Definitions

Previous: , Up: Packages   [Contents][Index]

4.5 commondoc-markdown/format

Source

file-type.lisp (file)

Use List

common-lisp

Exported Definitions

markdown (class)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *emit-section-anchors*

When this variable is ‘T‘ (default), emitter outputs a raw html ‘<a name="some-id"></a>‘ before each Markdown section.

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

By default it is ‘T‘, but you can bind it to NIL, to prevent short link references generation.

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Minumum length of the hash for generated markdown links.
This works only when *GENERATE-SHORT-LINK-REFERENCES* variable is set to ‘T‘.

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Package

commondoc-markdown

Source

file-type.lisp (file)

Function: make-raw-html-block HTML-STRING
Package

commondoc-markdown/raw-html

Source

file-type.lisp (file)

Function: make-raw-inline-html HTML-STRING
Package

commondoc-markdown/raw-html

Source

file-type.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Generic functions

Generic Function: html OBJECT
Package

commondoc-markdown/raw-html

Methods
Method: html (RAW-HTML raw-html)

automatically generated reader method

Source

file-type.lisp (file)

Package

commondoc-markdown

Methods

A definition slug for the linked document.

Source

file-type.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: markdown ()

The Markdown format.

Package

commondoc-markdown/format

Source

file-type.lisp (file)

Direct superclasses

document-format (class)

Direct methods
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • emit-document (method)
  • parse-document (method)
  • emit-document (method)
  • emit-document (method)

A named link like [Some text][the-id].

These links can be replaced with a web-link if id is defined somewhere in the markdown text.

Package

commondoc-markdown

Source

file-type.lisp (file)

Direct superclasses

link (class)

Direct methods
Direct slots
Slot: definition

A definition slug for the linked document.

Type

(or null string)

Initargs

:definition

Readers

markdown-link-definition (generic function)

Writers

(setf markdown-link-definition) (generic function)

Class: raw-html ()
Package

commondoc-markdown/raw-html

Source

file-type.lisp (file)

Direct superclasses

document-node (class)

Direct subclasses
Direct methods

html (method)

Direct slots
Slot: html
Type

string

Initargs

:html

Readers

html (generic function)

Class: raw-html-block ()
Package

commondoc-markdown/raw-html

Source

file-type.lisp (file)

Direct superclasses

raw-html (class)

Direct methods
  • emit (method)
  • emit-document (method)
Class: raw-inline-html ()
Package

commondoc-markdown/raw-html

Source

file-type.lisp (file)

Direct superclasses

raw-html (class)

Direct methods
  • emit (method)
  • emit-document (method)

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *create-node-recursive-call*
Package

commondoc-markdown

Source

file-type.lisp (file)

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Special Variable: *header-level*
Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Package

commondoc-markdown

Source

file-type.lisp (file)

Special Variable: *sections-stack*
Package

commondoc-markdown

Source

file-type.lisp (file)

Special Variable: *strikethrough*
Package

commondoc-markdown/addons

Source

file-type.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: go-deeper &body BODY
Package

commondoc-markdown

Source

file-type.lisp (file)

Macro: with-collected-references (NODES) &body BODY
Package

commondoc-markdown

Source

file-type.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: call-with-collected-references NODES FUNC
Package

commondoc-markdown

Source

file-type.lisp (file)

Function: create-node 3BMD-NODE
Package

commondoc-markdown

Source

file-type.lisp (file)

Function: find-url DEFINITION
Package

commondoc-markdown

Source

file-type.lisp (file)

Function: get-line-backticks-count LINE
Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Function: get-num-required-backticks CODE-TEXT

If code includes examples of markdown code blocks, then we should select higher number of backticks.

This function returns a number of backticks, required to wrap given CODE-TEXT into a Markdown code-block.

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Function: make-fence NUM-BACKTICKS
Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Function: make-inline-nodes PIECES

PIECES argument may contain a strings
or lists like (:CODE "foo").

Consecutive strings are concatenated into a text nodes, for lists a CREATE-NODE function is applied

Package

commondoc-markdown

Source

file-type.lisp (file)

Function: parse-markdown STRING

This is just a helper to reuse in tests

Package

commondoc-markdown

Source

file-type.lisp (file)

Function: write-header FORMAT TITLE STREAM
Package

commondoc-markdown/emitter

Source

file-type.lisp (file)

Function: write-header-prefix STREAM
Package

commondoc-markdown/emitter

Source

file-type.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Classes

Class: line-break ()

Explicit line break. In Markdown you have to add two or more spaces at the end of the line.

When rendered to HTML, this node will be replaced with <br/>.
When rendered back to markdown - with two spaces and a new-line.

Package

commondoc-markdown

Source

file-type.lisp (file)

Direct superclasses

markup (class)

Direct methods
  • emit (method)
  • emit-document (method)

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
commondoc-markdown.asd: The commondoc-markdown․asd file
commondoc-markdown/addons/file-type.lisp: The commondoc-markdown/addons/file-type․lisp file
commondoc-markdown/core/file-type.lisp: The commondoc-markdown/core/file-type․lisp file
commondoc-markdown/emitter/file-type.lisp: The commondoc-markdown/emitter/file-type․lisp file
commondoc-markdown/format/file-type.lisp: The commondoc-markdown/format/file-type․lisp file
commondoc-markdown/raw-html/file-type.lisp: The commondoc-markdown/raw-html/file-type․lisp file

F
File, Lisp, commondoc-markdown.asd: The commondoc-markdown․asd file
File, Lisp, commondoc-markdown/addons/file-type.lisp: The commondoc-markdown/addons/file-type․lisp file
File, Lisp, commondoc-markdown/core/file-type.lisp: The commondoc-markdown/core/file-type․lisp file
File, Lisp, commondoc-markdown/emitter/file-type.lisp: The commondoc-markdown/emitter/file-type․lisp file
File, Lisp, commondoc-markdown/format/file-type.lisp: The commondoc-markdown/format/file-type․lisp file
File, Lisp, commondoc-markdown/raw-html/file-type.lisp: The commondoc-markdown/raw-html/file-type․lisp file

L
Lisp File, commondoc-markdown.asd: The commondoc-markdown․asd file
Lisp File, commondoc-markdown/addons/file-type.lisp: The commondoc-markdown/addons/file-type․lisp file
Lisp File, commondoc-markdown/core/file-type.lisp: The commondoc-markdown/core/file-type․lisp file
Lisp File, commondoc-markdown/emitter/file-type.lisp: The commondoc-markdown/emitter/file-type․lisp file
Lisp File, commondoc-markdown/format/file-type.lisp: The commondoc-markdown/format/file-type․lisp file
Lisp File, commondoc-markdown/raw-html/file-type.lisp: The commondoc-markdown/raw-html/file-type․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   F   G   H   M   P   W  
Index Entry  Section

(
(setf markdown-link-definition): Exported generic functions
(setf markdown-link-definition): Exported generic functions

C
call-with-collected-references: Internal functions
create-node: Internal functions

F
find-url: Internal functions
Function, call-with-collected-references: Internal functions
Function, create-node: Internal functions
Function, find-url: Internal functions
Function, get-line-backticks-count: Internal functions
Function, get-num-required-backticks: Internal functions
Function, hash-link: Internal functions
Function, make-fence: Internal functions
Function, make-inline-nodes: Internal functions
Function, make-markdown-link: Exported functions
Function, make-raw-html-block: Exported functions
Function, make-raw-inline-html: Exported functions
Function, parse-markdown: Internal functions
Function, write-header: Internal functions
Function, write-header-prefix: Internal functions

G
Generic Function, (setf markdown-link-definition): Exported generic functions
Generic Function, html: Exported generic functions
Generic Function, markdown-link-definition: Exported generic functions
get-line-backticks-count: Internal functions
get-num-required-backticks: Internal functions
go-deeper: Internal macros

H
hash-link: Internal functions
html: Exported generic functions
html: Exported generic functions

M
Macro, go-deeper: Internal macros
Macro, with-collected-references: Internal macros
make-fence: Internal functions
make-inline-nodes: Internal functions
make-markdown-link: Exported functions
make-raw-html-block: Exported functions
make-raw-inline-html: Exported functions
markdown-link-definition: Exported generic functions
markdown-link-definition: Exported generic functions
Method, (setf markdown-link-definition): Exported generic functions
Method, html: Exported generic functions
Method, markdown-link-definition: Exported generic functions

P
parse-markdown: Internal functions

W
with-collected-references: Internal macros
write-header: Internal functions
write-header-prefix: Internal functions

Jump to:   (  
C   F   G   H   M   P   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
D   H   S  
Index Entry  Section

*
*create-node-recursive-call*: Internal special variables
*emit-section-anchors*: Exported special variables
*generate-short-link-references*: Exported special variables
*hash->link*: Internal special variables
*header-level*: Internal special variables
*link->hash*: Internal special variables
*link-references*: Internal special variables
*min-link-hash-length*: Exported special variables
*sections-stack*: Internal special variables
*strikethrough*: Internal special variables

D
definition: Exported classes

H
html: Exported classes

S
Slot, definition: Exported classes
Slot, html: Exported classes
Special Variable, *create-node-recursive-call*: Internal special variables
Special Variable, *emit-section-anchors*: Exported special variables
Special Variable, *generate-short-link-references*: Exported special variables
Special Variable, *hash->link*: Internal special variables
Special Variable, *header-level*: Internal special variables
Special Variable, *link->hash*: Internal special variables
Special Variable, *link-references*: Internal special variables
Special Variable, *min-link-hash-length*: Exported special variables
Special Variable, *sections-stack*: Internal special variables
Special Variable, *strikethrough*: Internal special variables

Jump to:   *  
D   H   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   L   M   P   R   S  
Index Entry  Section

C
Class, line-break: Internal classes
Class, markdown: Exported classes
Class, markdown-link: Exported classes
Class, raw-html: Exported classes
Class, raw-html-block: Exported classes
Class, raw-inline-html: Exported classes
commondoc-markdown: The commondoc-markdown system
commondoc-markdown: The commondoc-markdown package
commondoc-markdown/addons: The commondoc-markdown/addons system
commondoc-markdown/addons: The commondoc-markdown/addons package
commondoc-markdown/core: The commondoc-markdown/core system
commondoc-markdown/emitter: The commondoc-markdown/emitter system
commondoc-markdown/emitter: The commondoc-markdown/emitter package
commondoc-markdown/format: The commondoc-markdown/format system
commondoc-markdown/format: The commondoc-markdown/format package
commondoc-markdown/raw-html: The commondoc-markdown/raw-html system
commondoc-markdown/raw-html: The commondoc-markdown/raw-html package

L
line-break: Internal classes

M
markdown: Exported classes
markdown-link: Exported classes

P
Package, commondoc-markdown: The commondoc-markdown package
Package, commondoc-markdown/addons: The commondoc-markdown/addons package
Package, commondoc-markdown/emitter: The commondoc-markdown/emitter package
Package, commondoc-markdown/format: The commondoc-markdown/format package
Package, commondoc-markdown/raw-html: The commondoc-markdown/raw-html package

R
raw-html: Exported classes
raw-html-block: Exported classes
raw-inline-html: Exported classes

S
System, commondoc-markdown: The commondoc-markdown system
System, commondoc-markdown/addons: The commondoc-markdown/addons system
System, commondoc-markdown/core: The commondoc-markdown/core system
System, commondoc-markdown/emitter: The commondoc-markdown/emitter system
System, commondoc-markdown/format: The commondoc-markdown/format system
System, commondoc-markdown/raw-html: The commondoc-markdown/raw-html system

Jump to:   C   L   M   P   R   S