edf-to-html-converter

This README explains just the basic idea behind the project. No comprehensive examples are given here.

Detailed Documentation (work in progress) :

1. Markup Parser docs
2. Html Mapper docs

How To Install

npm install edf-to-html-converter

Yoman Scaffolding Project

Automatically creates the basic file structure - yoman project

npm install -g generator-edf-to-html-converter

yo edf-to-html-converter

What Is The Edf To Html Converter npm Package

The edfToHtmlConverter is a simple text-to-html converter intended to be used for creating quick reference guides to books and other learning materials. It is intended to work offline and on any resolution. Links to resources are provided by variables, which gives flexibility when moving files to different directories.

What Is The Motivation Behind The Project And Why Not Use Any Existing Tools

If you are taking notes on a lecture or on a book there are a couple of things to keep in mind :

1. The notes can't be too brief or they won't be useful.
2. They also can't be too long because they become to hard to navigate. In this situation it might take less time to find what you are looking for on the Internet.
3. Having links between files makes navigation much quicker than putting information in a single big document.
4. It's good if the generated output works with different resolutions. So you could use the same notes with different devices.
5. It's important that the styles are custom and help you navigate quicker.
6. Maintaining the same style for all notes helps the brain to learn quicker.
7. When maintaining notes from different sources it's often possible that better explanations are found along the way, in which case the folder structure might change rapidly.

I believe that all these requirements could be meet by the Browser.

There haven't been many tools that cover all these in the exact way I want. There are a lot of formats that can be used to create documents - LaTeX, TeX, MD and other. LaTeX and TeX are great tools, but they take a significant amount of time to master and are not intended for the Web. Markdown(MD) is not comprehensive enough. Also if you are not in control of the tag generation you can't have the flexibility of creating your own css styles.

For all these reasons I decided to make my own tool for the job.

How It Works

The library uses es6 !

The library operates on a folder structure. As a absolute minimum it requires an in/ and a out/ folder.

This example :

  in
  |-> dir
  |   |-> resources
  |   |   |-> favicon.ico
  |   |   |-> resource.gif
  |   |-> fileTwo.edf
  |   |-> fileThree.edf
  |-> fileOne.edf

Compiles to :

  out
  |-> dir
  |   |-> resources
  |   |   |-> favicon.ico
  |   |   |-> resource.gif
  |   |-> fileTwo.html
  |   |-> fileThree.html
  |-> lib
  |   |-> highlight
  |   |   |-> ...
  |-> style
  |   |-> style.css
  |-> .settings.json
  |-> .tracking.json
  |-> .varReferences.json
  |-> fileOne.html

what happened ?

1. The .edf files are converted to .html and everything else is copied.
2. The folder lib was created, which is used for third-party libraries that help for code highlighting and other tasks.
3. The style folder is copied which contains the style.css default theme.
4. The .settings.json file saves settings and variables used in the project.
5. The .tracking.json is used to track the lastModified time of all files. This is done to avoid re-compiling .edf files that haven't been changed and re-coping the resource files.
6. The .varReferences.json keeps tracks of references to variables in different files. When a variable changes it's value or is deleted - the files that reference it must be re-compiled !

The most basic use :

var app = require('./index')
let settings = {
  IN_DIR: './in',
  OUT_DIR: './out'
}

app.run(settings)

(note) Obviously don't name folders in your in/ directory as style or lib !

The Easy Document Format (EDF) Templates

The EDF syntax is entirely customizable via templates. A Template has

1. #attrs# writes out all attributes in order.
2. #attr.attrName# writes just the value of a given attribute and removes it from #attrs#.
3. #content# writes the content of the tag.

Example:

  <p #attrs#>#attr.class# <b>#content#</b><p>

using the above template we could translate this :

  <p class="def" id="hij" name="test">ABC<p>

to :

  <p id="hij" name="test">def <b>ABC</b></p>

The Default Templates

Edf	Html
p	<p #attrs#>#content#</p>
b	<b #attrs#>#content#</b>
ul	<ul #attrs#>#content#</ul>
li	<li #attrs#>#content#</li>
h1	<h1 #attrs#>#content#</h1>
h2	<h2 #attrs#>#content#</h2>
h3	<h3 #attrs#>#content#</h3>
h4	<h4 #attrs#>#content#</h4>
h5	<h5 #attrs#>#content#</h5>
h6	<h6 #attrs#>#content#</h6>
dl	<dl #attrs#>#content#</dl>
dt	<dt #attrs#>#content#</dt>
dd	<dd #attrs#>#content#</dd>
sub	<sub #attrs#>#content#</sub>
sup	<sup #attrs#>#content#</sup>
a	<a #attrs#>#content#</a>
img	<img #attrs# />
important	<div #attrs#>#content#</div>
console	<div #attrs#>#content#</div>
cl	<div #attrs#>&gt;#content#</div>
co	<div #attrs#>#content#</div>
code	<div #attrs#><pre><code class="#attr.lang#">#content#</code></pre></div> This tag uses the HighlightJs library
math	<div #attrs#>$$#content#$$</div> This tag uses the MathJax library with only LaTex support.

The Settings Object

The global settings :

Option	Type	Default Value	Meaning
IN_DIR	String	'./in'	Specifies the input directory.
OUT_DIR	String	'./out'	Specifies the output directory.
COMPRESS_DIR	String	null	Creates a compressed version of the IN_DIR and the OUT_DIR. Experimental use only.
stopTrackingFiles	Boolean	false	Clears the out directory on every compilation
autoMapFilesToVars	Boolean	true	Maps all files to variables
stopDefaultStyle	Boolean	false	Removes the default css and javascript from the page globally
variables	Object	null	Defines global variables
templates	Object	null	User specific templates
styleCDNs	Array	[]	Adds these cdns as link tags in the head
scriptCDNs	Array	[]	Adds these cdns as script tags in the footer
useMath	Boolean	false	Adds the cdn to MathJax
codeTagStyle	String	'monokai-sublime.css'	Sets the color scheme for highlightjs

The local settings :

Option	Type	Default Value	Meaning
variables	Object	null	Defines local variables that override the global variables
styleCDNs	Array	[]	Adds these cdns as link tags in the head
scriptCDNs	Array	[]	Adds these cdns as script tags in the footer
useMath	Boolean	false	Adds the cdn to MathJax
title	String	false	The page title

Variables

There are two types of variables you can register :

let settings = {
  variables : {
    // For variables that are used as paths in IMG or A tags :
    _testPathVar: {
      value: './dir/something.txt',
      type: 'path'
    },
    // The normal variables simply get replaced in the .edf file :
    _testNormalVar: {
      value: 'This could be a heading.',
      type: 'normal'
    }
  }
}

In the .edf file :

<a href="$(_testPathVar)"></a>
<h1>$(_testNormalVar)</h1>

Generates .html (the actual result is minified) :

<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <link rel="stylesheet" href="style/style.css">
  <link rel="stylesheet" href="lib/highlight/styles/monokai-sublime.css">
  <script src="lib/highlight/highlight.pack.js"></script>
  <script>hljs.initHighlightingOnLoad()</script>
  <title>index</title>
</head>

<body>
  <div class="container">
    // the number of ../ depends on where the file is in the filesystem :
    <a class="default-a" href="../../dir/something.txt">Test</a>
    <h1 class="default-h1">This could be a heading.</h1>
  </div>
</body>

</html>