diff --git a/README.md b/README.md index 8e48c16..49dee35 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Code Climate](https://codeclimate.com/github/jeffreytse/jekyll-spaceship/badges/gpa.svg)](https://codeclimate.com/github/jeffreytse/jekyll-spaceship) [![Test Coverage](https://api.codeclimate.com/v1/badges/cd56b207f327603662a1/test_coverage)](https://codeclimate.com/github/jeffreytse/jekyll-spaceship/test_coverage) -A Jekyll plugin to provide powerful supports for table, mathjax, plantuml, etc. +A Jekyll plugin to provide powerful supports for table, mathjax, plantuml, youtube, etc. ## Table of Contents @@ -17,14 +17,23 @@ A Jekyll plugin to provide powerful supports for table, mathjax, plantuml, etc. - [1.2 Multiline](#multiline) - [1.3 Headerless](#headerless) - [1.4 Cell Alignment](#cell-alignment) + - [1.5 Cell Markdown](#cell-markdown) - [2. MathJax Usage](#2-mathjax-usage) - [3. PlantUML Usage](#3-plantuml-usage) + - [4. Video Usage](#4-video-usage) + - [4.1 Youtube Usage](#youtube-usage) + - [4.2 Vimeo Usage](#vimeo-usage) + - [4.3 DailyMotion Usage](#dailymotion-usage) + - [5. Hybrid HTML with Markdown](#5-hybrid-html-with-markdown) + - [6. Markdown Polyfill](#6-markdown-polyfill) + - [6.1 Escape Ordered List](#escape-ordered-list) - [Credits](#credits) - [Contributing](#contributing) - [License](#license) ## Requirements -* Ruby >= 2.3.0 + +- Ruby >= 2.3.0 ## Installation @@ -47,28 +56,29 @@ plugins: **For now, these extended features are provided:** -* Cells spanning multiple columns -* Cells spanning multiple rows -* Cells text align separately -* Table header not required -* Grouped table header rows or data rows +- Cells spanning multiple columns +- Cells spanning multiple rows +- Cells text align separately +- Table header not required +- Grouped table header rows or data rows Noted that GitHub filters out style property, so the example displays with the obsolete align property. But in actual this plugin outputs style property with text-align CSS attribute. #### Rowspan and Colspan + ^^ in a cell indicates it should be merged with the cell above. This feature is contributed by [pmccloghrylaing](https://github.com/pmccloghrylaing). ```markdown -| Stage | Direct Products | ATP Yields | -| ----: | --------------: | ---------: | -|Glycolysis | 2 ATP || -|^^ | 2 NADH | 3--5 ATP | -|Pyruvaye oxidation | 2 NADH | 5 ATP | -|Citric acid cycle | 2 ATP | | -|^^ | 6 NADH | 15 ATP | -|^^ | 2 FADH | 3 ATP | -| 30--32 ATP ||| +| Stage | Direct Products | ATP Yields | +| -----------------: | --------------: | ---------: | +| Glycolysis | 2 ATP | | +| ^^ | 2 NADH | 3--5 ATP | +| Pyruvaye oxidation | 2 NADH | 5 ATP | +| Citric acid cycle | 2 ATP || +| ^^ | 6 NADH | 15 ATP | +| ^^ | 2 FADH | 3 ATP | +| 30--32 ATP ||| ``` Code above would be parsed as: @@ -114,18 +124,19 @@ Code above would be parsed as: #### Multiline + A backslash at end to join cell contents with the following lines. This feature is contributed by [Lucas-C](https://github.com/Lucas-C). ```markdown -|: Easy Multiline :||| -|:------ |:------ |:-------- | -| Apple | Banana | Orange \ -| Apple | Banana | Orange \ -| Apple | Banana | Orange -| Apple | Banana | Orange \ -| Apple | Banana | Orange | -| Apple | Banana | Orange | +| : Easy Multiline : ||| +| :----- | :----- | :------ | +| Apple | Banana | Orange \ +| Apple | Banana | Orange \ +| Apple | Banana | Orange +| Apple | Banana | Orange \ +| Apple | Banana | Orange | +| Apple | Banana | Orange | ``` Code above would be parsed as: @@ -156,18 +167,19 @@ Code above would be parsed as: #### Headerless + Table header can be eliminated. ```markdown |--|--|--|--|--|--|--|--| -|♜| |♝|♛|♚|♝|♞|♜| -| |♟|♟|♟| |♟|♟|♟| -|♟| |♞| | | | | | -| |♗| | |♟| | | | -| | | | |♙| | | | -| | | | | |♘| | | -|♙|♙|♙|♙| |♙|♙|♙| -|♖|♘|♗|♕|♔| | |♖| +|♜| |♝|♛|♚|♝|♞|♜| +| |♟|♟|♟| |♟|♟|♟| +|♟| |♞| | | | | | +| |♗| | |♟| | | | +| | | | |♙| | | | +| | | | | |♘| | | +|♙|♙|♙|♙| |♙|♙|♙| +|♖|♘|♗|♕|♔| | |♖| ``` Code above would be parsed as: @@ -258,21 +270,22 @@ Code above would be parsed as: #### Cell Alignment + Markdown table syntax use colons ":" for forcing column alignment. -Therefore, here we also use it for foring cell alignment. +Therefore, here we also use it for foring cell alignment. Table cell can be set alignment separately. -``` -|: Fruits \|\| Food :||| -|:-------- |:-------- |:------------ | -| Apple |: Apple :| Apple \ -| Banana | Banana | Banana \ -| Orange | Orange | Orange | -|: Rowspan is 4 :|| How's it? | -|^^ A. Peach || 1. Fine :| -|^^ B. Orange ||^^ 2. Bad | -|^^ C. Banana || It's OK! | +```markdown +| : Fruits \|\| Food : ||| +| :--------- | :-------- | :-------- | +| Apple | : Apple :| Apple \ +| Banana | Banana | Banana \ +| Orange | Orange | Orange | +| : Rowspan is 4 : || How's it? | +|^^ A. Peach || 1. Fine :| +|^^ B. Orange ||^^ 2. Bad | +|^^ C. Banana || It's OK! | ``` Code above would be parsed as: @@ -309,22 +322,79 @@ Rowspan is 4 +#### Cell Markdown + +Sometimes we may need some abundant content (e.g., mathjax, image, video) in Markdown table +Therefore, here we also make markown syntax possible inside a cell. + +```markdown +| : MathJax \|\| Image : ||| +| :------------ | :-------- | :----------------------------- | +| Apple | : Apple : | Apple \ +| Banana | Banana | Banana \ +| Orange | Orange | Orange | +| : Rowspan is 4 : || : How's it? : | +| ^^ A. Peach || 1. ![example][cell-image] | +| ^^ B. Orange || ^^ 2. $I = \int \rho R^{2} dV$ | +| ^^ C. Banana || **It's OK!** | + +[cell-image]: https://jekyllrb.com/img/octojekyll.png "An exemplary image" +``` + +Code above would be parsed as: + + + + + + + + + + + + + + + + + + + + + + + + + +
MathJax || Image +
Apple
Banana
Orange		Apple
Banana
Orange		Apple
Banana
Orange
+Rowspan is 4 +
A. Peach +
B. Orange +
C. Banana +
How's it?
+
    +
    2. +
    3. +
+
It' OK!
### 2. MathJax Usage + [MathJax](http://www.mathjax.org/) is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation that works in all modern browsers. **Some of the main features of MathJax include:** -* High-quality display of LaTeX, MathML, and AsciiMath notation in HTML pages -* Supported in most browsers with no plug-ins, extra fonts, or special +- High-quality display of LaTeX, MathML, and AsciiMath notation in HTML pages +- Supported in most browsers with no plug-ins, extra fonts, or special setup for the reader -* Easy for authors, flexible for publishers, extensible for developers -* Supports math accessibility, cut-and-paste interoperability, and other +- Easy for authors, flexible for publishers, extensible for developers +- Supports math accessibility, cut-and-paste interoperability, and other advanced functionality -* Powerful API for integration with other web applications +- Powerful API for integration with other web applications - -Put your math expression within \$...\$ +Put your math expression within \\\\\\\\\$...\$ ```markdown $ a * b = c ^ b $ @@ -339,31 +409,177 @@ $ \int\_a^b f(x)\,dx. $ ``` ### 3. PlantUML Usage -[PlantUML](http://plantuml.sourceforge.net/) is a component that allows to quickly write: - * sequence diagram, - * use case diagram, - * class diagram, - * activity diagram, - * component diagram, - * state diagram - * object diagram +[PlantUML](http://plantuml.sourceforge.net/) is a component that allows to quickly write: + +- sequence diagram, +- use case diagram, +- class diagram, +- activity diagram, +- component diagram, +- state diagram +- object diagram There are two ways to create a diagram in your Jekyll blog page: +````markdown +```plantuml +Bob -> Alice : hello world +``` +```` + +or + ```markdown @startuml Bob -> Alice : hello @enduml ``` -or +### 4. Video Usage -````markdown -``` plantuml -Bob -> Alice : hello world +How often did you find yourself googling "**How to embed a video in markdown?**" + +While its not possible to embed a video in markdown, the best and easiest way is to extract a frame from the video. To add videos to your markdown files easier I developped this tool for you, and it will parse the video link inside the image block automatically. + +**For now, these video links parsing are provided:** + +- Youtube +- Vimeo +- DailyMotion + +There are two ways to embed a video in your Jekyll blog page: + +Inline-style: + +```markdown +![]({video-link}) +``` + +Reference-style: + +```markdown +![][{reference}] + +[{reference}]: {video-link} +``` + +For configuring video attributes (e.g, width, height), just adding query string to +the link as below: + +```markdown +![](https://www.youtube.com/watch?v=Ptk_1Dc2iPY?width=800&height=500) +``` + +```markdown +![](https://www.dailymotion.com/video/x7tfyq3?width=100%&height=400) +``` + +#### Youtube Usage + +```markdown +![](https://www.youtube.com/watch?v=Ptk_1Dc2iPY) +``` + +```markdown +![](//www.youtube.com/watch?v=Ptk_1Dc2iPY?width=800&height=500) +``` + +#### Vimeo Usage + +```markdown +![](https://vimeo.com/263856289) +``` + +```markdown +![](https://vimeo.com/263856289?width=500&height=320) +``` + +#### DailyMotion Usage + +```markdown +![](https://www.dailymotion.com/video/x7tfyq3) +``` + +```markdown +![](https://dai.ly/x7tgcev?width=100%&height=400) +``` + +### 5. Hybrid HTML with Markdown + +As markdown is not only a lightweight markup language with plain-text-formatting syntax, but also an easy-to-read and easy-to-write plain text format, so writing a hybrid HTML with markdown is an awesome choice. + +It's easy to write markdown inside HTML: + +```html + +``` + +### 6. Markdown Polyfill + +It allows us to polyfill features for extending markdown syntax. + +**For now, these polyfill features are provided:** + +- Escape ordered list + +#### Escape Ordered List + +A backslash at begin to escape the ordered list. + +```markdown +Normal: + +1. List item Apple. +3. List item Banana. +10. List item Cafe. + +Escaped: + +\1. List item Apple. +\3. List item Banana. +\10. List item Cafe. +``` + +Code above would be parsed as: + +```markdown +Normal: + +1. List item Apple. +2. List item Banana. +3. List item Cafe. + +Escaped: + +1. List item Apple. +3. List item Banana. +10. List item Cafe. ``` -```` ## Credits @@ -378,4 +594,5 @@ Issues and Pull Requests are greatly appreciated. If you've never contributed to You can start by [opening an issue](https://github.com/jeffreytse/jekyll-spaceship/issues/new) describing the problem that you're looking to resolve and we'll go from there. ## License + This software is licensed under the [MIT license](https://opensource.org/licenses/mit-license.php) © JeffreyTse.