CLI (command line) application to generate HTML file of tutorials for Javascript librarries. It takes an enhance markdown file with some minor extensions and creates an HTML file. The HTML tutorial file (a try file) requires no backend server, and totally self contained.
> tryitjs basic.tryCreates a HTML file
basic.htmltutorial file.
In the tutorial descriptions contails markdown and snippets of editable Javascript code. Snippets that can be edited and executed in the browser. This makes it effortless to someone try out the capabilities of a Javascript library. Explore its capability to see iif it could be useful, play with the code snippets to understand the capability of the library quickly in the browser. It requires a minimum of effort and no installation or setup.
The primary goal is to help npm module developers to publish pages for other developers so that can try out ther library with the minimum of effort.
Screenshot of a sample HTML
The image below is a example of a generated HTML with some annotations
Note You can save your edits (in the browser's local storage) so you can come back to it at a later date.
Development status
The code is in good shape and is ready for developers to use. The documentation is still work in progress, but this site as some good example for you to use. As always, time allowing, I would like to add more capabilities in the future.
Links to demos
A more extensive example on how to create a Tutorial, examples of how to use DataFrame library used for data analysis and data visualization (see: GitHub data-frame repo). The data used for the examples is the worldwide covid dataset consisting of over 105K rows). THe data-frame package was developed by me for some of my personal use and professional project.
Why TryTTjs
As with most github project, it was to meet a need I had, namely to delevop an interactive tutorial for a JS library I had developed - DataTable loosly base of Python's Pandas library. DataFrame. The tool is powerful, but it is not easy for others to know how to use it and what you can do with it. The tutorial is written as a text file(s) in an exxtended markdown similar to this document. Interspesed with the markdown ther is runnable javascript code. That can be executed and edited to get hands on experiece with the ideas and api.
Any number of utilities and libraries can be included with the tutorial. Besides markdown, sections can how the full power of HTML as well as Javascript. I have found it easier to write a tutorial if ther is a step by step guide working through a real problem. TryITjs creates an standalone HTML page with no backend server required (except to deliver the page).
Documentation - Work in progrress 🚧
<img src="images/basic.png"width="600"/>
User Interface
Instalation
Install globally
npm install -g tryitjsQuickly try it out
- Start a command prompt (bash on Linux, cmd on Windows,...)
- Navigate to an empty directory (or you outer level projects directory)
tryitjs --init my-try-playpenYou will see that a new directory has been created my-try-playpen
Switch to the the playpen directory as follows:
cd my-try-playpen
npm install
npm run build
npm startSimplest usage
Example of HTML generated
The following command can be used to generate a .HTML file from a .try file
> tryitjs basic.tryThe command above generates and
basic.html (click to see live results)
Idea for the future - pure HTML file that lets you edit an preview simple .try files. TryIJjs should be able to do it, the API can run in a browser (by design) but I have not tried that usecase, so I am not sure it will work out of the box.
What is a .try file
Very it is a markdown file with a few simple extensions, .try file have the following few commands:
Multi-line markup
| command | Sescription |
|---|---|
| !head | Items to be added to the <head> add all subsequent lines become part of html/head until the next command |
| !md | Subsequent lines are treated as markdown |
| !tryit | the subsequent lines are editable and executable javascript |
| !html | the subsequent lines are plain html fragments |
!head
<link <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.2.0/build/styles/default.min.css" />
<script src="javascript/tryit.js"></script>
!md -- end the !head and starts markdown segment
# This is a title
...
!tryit -- start some javascript
let arr = [1, 2, 3];
x
Single line markup
Does not end the previously started command section, in these single-line command can be a part oone of the previous command
| command | Description |
|---|---|
| @@include <file name> | copy the contents of the file into the current location |
| @@include ESCAPE <file name> | display the contents of the file |
| @@once | If this annotaion is present in a file to be included, The file is included once. Any subsequent @@include of the same file will be ignored. Note: This must be the first file of a file to be included |
| !-- | the rest of the line is a comment |
Run from command prompt
- locally installed
node_modules/.bin/tryitjs {-d target-directory} {-src source-dir}
- Globally installed
tryitjs {--dest target-directory}
- or more generally
tryitjs --src <src dir for .try files> --dest <target dir for generated .html files> { --local }
=======
CLI (command line) application to generate HTML file of tutorials for Javascript librarries. It takes an enhance markdown file with some minor extensions and creates an HTML file. The HTML tutorial file (a try file) requires no backend server, and totally self contained.
> tryitjs basic.tryCreates a HTML file
basic.htmltutorial file.
graph LR
A{{basic.try}} --> B(tryitjs) --> H{{basic.html}}
In the tutorial descriptions contails markdown and snippets of editable Javascript code. Snippets that can be edited and executed in the browser. This makes it effortless to someone try out the capabilities of a Javascript library. Explore its capability to see iif it could be useful, play with the code snippets to understand the capability of the library quickly in the browser. It requires a minimum of effort and no installation or setup.
The primary goal is to help npm module developers to publish pages for other developers so that can try out ther library with the minimum of effort.
Screenshot of a sample HTML
The image below is a example of a generated HTML with some annotations
Note You can save your edits (in the browser's local storage) so you can come back to it at a later date.
Development status
The code is in good shape and is ready for developers to use. The documentation is still work in progress, but this site as some good example for you to use. As always, time allowing, I would like to add more capabilities in the future.
Links to demos
A more extensive example on how to create a Tutorial, examples of how to use DataFrame library used for data analysis and data visualization (see: GitHub data-frame repo). The data used for the examples is the worldwide covid dataset consisting of over 105K rows). THe data-frame package was developed by me for some of my personal use and professional project.
Why TryTTjs
As with most github project, it was to meet a need I had, namely to delevop an interactive tutorial for a JS library I had developed - DataTable loosly base of Python's Pandas library. DataFrame. The tool is powerful, but it is not easy for others to know how to use it and what you can do with it. The tutorial is written as a text file(s) in an exxtended markdown similar to this document. Interspesed with the markdown ther is runnable javascript code. That can be executed and edited to get hands on experiece with the ideas and api.
Any number of utilities and libraries can be included with the tutorial. Besides markdown, sections can how the full power of HTML as well as Javascript. I have found it easier to write a tutorial if ther is a step by step guide working through a real problem. TryITjs creates an standalone HTML page with no backend server required (except to deliver the page).
Documentation - Work in progrress 🚧
<img src="images/basic.png"width="600"/>
User Interface
Instalation
Install globally
npm install -g tryitjsQuickly try it out
- Start a command prompt (bash on Linux, cmd on Windows,...)
- Navigate to an empty directory (or you outer level projects directory)
tryitjs --init my-try-playpenYou will see that a new directory has been created my-try-playpen
Switch to the the playpen directory as follows:
cd my-try-playpen
npm install
npm run build
npm startSimplest usage
Example of HTML generated
The following command can be used to generate a .HTML file from a .try file
> tryitjs basic.tryThe command above generates and
basic.html (click to see live results)
What is a .try file
Very it is a markdown file with a few simple extensions, .try file have the following few commands:
Multi-line markup
| command | Sescription |
|---|---|
| !head | Items to be added to the <head> add all subsequent lines become part of html/head until the next command |
| !md | Subsequent lines are treated as markdown |
| !tryit | the subsequent lines are editable and executable javascript |
| !html | the subsequent lines are plain html fragments |
!head
<link <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.2.0/build/styles/default.min.css" />
<script src="javascript/tryit.js"></script>
!md -- end the !head and starts markdown segment
# This is a title
...
!tryit -- start some javascript
let arr = [1, 2, 3];
x
Single line markup
Does not end the previously started command section, in these single-line command can be a part oone of the previous command
| command | Description |
|---|---|
| @@include <file name> | copy the contents of the file into the current location |
| @@include ESCAPE <file name> | display the contents of the file |
| @@once | If this annotaion is present in a file to be included, The file is included once. Any subsequent @@include of the same file will be ignored. Note: This must be the first file of a file to be included |
| !-- | the rest of the line is a comment |
Run from command prompt
- locally installed
node_modules/.bin/tryitjs {-d target-directory} {-src source-dir}
- Globally installed
tryitjs {--dest target-directory}
- or more generally
tryitjs --src <src dir for .try files> --dest <target dir for generated .html files> { --local }