docuvert v0.0.3
= docuvert
https://www.npmjs.com/package/docuvert:[image:https://img.shields.io/npm/v/docuvert.svg?style=flat-square[npm version badge]] image:https://img.shields.io/david/zorceta/docuvert.svg?style=flat-square[David dependencies badge] image:https://img.shields.io/david/dev/zorceta/docuvert.svg?style=flat-square[David dev dependencies badge]
A document converter for JavaScript.
== Quick start
shell
$ npm i docuvert docuvert-format-what-you-need
--save
source,javascript
import * as docuvert from 'docuvert' docuvert.loadFormats( require('docuvert-format-asciidoc'), require('docuvert-format-html') )
let content = `= docuvert
A document converter for JavaScript. `
let converted = docuvert.convert('asciidoc', 'html', content)
== Usage
docuvert itself is only a shell for formatters to unleash their power.
So, before using it, prepare formatters of all the formats you need.
source,javascript
import * as docuvert from 'docuvert' docuvert.loadFormats([ require('docuvert-format-asciidoc'), require('docuvert-format-html')
])
Then, if your content needs to be converted to only one format
source,javascript
let converted = docuvert.convert(
'asciidoc',
'html',
= docuvert
A document converter for JavaScript.
)
Or, if more than one format is needed
source,javascript
let formatsNeeded = 'html', 'markdown', 'restructuredtext', 'pdf', document = docuvert.Document.from('asciidoc', content), converted = {}
formatsNeeded.forEach(formatName => { convertedformatName = document.to(formatName)
})
Or, if you are not sure which formats are needed
source,javascript
let document = docuvert.Document.from('asciidoc', content), toFormat = input('Which format do you want?'),
converted = document.to(toFormat)
== API
=== docuvert
==== docuvert.Document
===== Document.from(fromFormat, content, options)
Returns a Document
instance representing content
.
fromFormat
required the formatcontent
is incontent
required names itselfoptions
optional passed to formatter
===== document.to(toFormat, options)
Returns document
(a Document
instance) in toFormat
format.
toFormat
required the format you wantdocument
inoptions
optional passed to formatter
==== docuvert.convert(fromFormat, toFormat, content, options)
Returns content
, which is originally in fromFormat
, in toFormat
.
fromFormat
required the formatcontent
is intoFormat
required the format you wantcontent
incontent
required names itselfoptions
optionalfrom
optional passed to formatterto
optional passed to formatter
== Formatters
docuvert relies heavily on formatters. Itself without formatters is like a company without its staff.
A formatter must have these properties
- string
formatName
required full name of the format this formatter is for .from(content, options)
turnscontent
into aDocument
instancecontent
required names itselfoptions
optional names itself.to(options)
turns aDocument
instance into a text in the format this formatter is for **options
optional names itself
Implementation details are not cared about.
=== Document tree and elements
docuvert abstracts the structure of a document into a tree, and several elements that form a tree.
==== Common characteristics of elements
- All elements have following properties
parent
parent of that element on the document tree,
an instance of an Element
sub"class"
attributes
attributes of that element,
an object
acting as a dictionary, with the name Attributes
an object
acting as a dictionary, with the name Style
All listed attributes are always present, generated by the constructor. + An attribute marked
required
is immutable, thus must be provided on element creation. + Similarly, an attribute markedoptional
is mutable, and can be later changed (which usually can not be filled on element creation).content
attribute, if not explicitly specified, is anArray
containing child elements of that element.Image
,Audio
andVideo
elements have thesource
attribute that may be a URI or path that points to their source, rather than containing the content. + Formatters dealing with formats that contain all resources in a single file, such as PDF, should notice this.
==== Element
This is the base class (prototype). It sets the default attributes. Not for direct use.
==== ElementWithContents
A convenience base class.
- Array
children
names itself .addContent(content)
equivalent to.children.push(content)
==== Document
a.k.a. docuvert.Document
.
This is a special element, the instance of which represents a document, the tree of it, and the root of its tree.
Its parent
attribute always is and must be null.
==== Text(content)
Names itself. The most basic element.
- string
type
requiredtext
a piece of textspan
a group of text children
requiredtype='text'
a stringtype='span'
anArray
ofText
.addContent(content)
type='text'
equivalent to.children = content
type='span'
equivalent to.children.push(content)
Here are a number of possible attributes
bold
, italic
, strikethrough
, underline
, monospace
,
strong
, emphasis
, small
, mark
(highlight),
superscript
, subscript
that all name themselves and are very common.
==== Image(source)
Represents an image.
- string
source
required names itself
==== Audio(source)
Represents an audio.
- string
source
required names itself
==== Video(source)
Represents a video.
- string
source
required names itself
==== Link(link) extends ElementWithContents
The most basic element for the Internet.
- string
link
required names itself
==== Heading(level) extends ElementWithContents
Names itself.
- number
level
required names itself
==== List(ordered) extends ElementWithContents
Names itself.
- boolean
ordered
required names itself
===== List.Item extends ElementWithContents
Names itself.
==== Table
Names itself.
- Table.Body
body
optional names itself - Table.Header
header
optional names itself - Table.Footer
footer
optional names itself
===== Table.Body extends ElementWithContents
Names itself.
===== Table.Header extends ElementWithContents
Names itself.
===== Table.Footer extends ElementWithContents
Names itself.
===== Table.Row extends ElementWithContents
Names itself.
===== Table.Cell extends ElementWithContents
Names itself.
==== Paragraph extends ElementWithContents
Names itself.
==== Quotation(inline, type) extends ElementWithContents
Names itself.
- boolean
inline
required is this quotation inline or a block, i.e.<q>
or<blockquote>
using HTML as an example. - string
type
required can be the following"text"
names itself"code"
names itself
==== Block extends ElementWithContents
A section that divides an area from its parent, whether for content grouping or styling purpose.
==== Raw extends ElementWithContents
A not escaped piece of content, usually in another format, embedded in current format.
==== Comment extends ElementWithContents
Uh. Seems every single language in this world supports comment.
==== LineBreak
When a piece of text needs to be in two separate lines, meanwhile needs not be in two paragraphs. The same for other types of content.
No content.
== License
Copyright (c) 2015 https://github.com/zorceta[Zorceta Moshak].
Code licensed under https://opensource.org/licenses/BSD-3-Clause[BSD 3-Clause]. LICENSE.txt
under the root directory is a copy of the license text.