sharpetronics/jekyll-spaceship
1
0
Fork 0
mirror of https://github.com/SharpeTronics/jekyll-spaceship.git synced 2025-12-20 00:01:55 -05:00
Code Issues Projects Releases Wiki Activity

docs: update README.md

Browse Source
This commit is contained in:
jeffreytse 2020-04-29 01:04:11 +08:00
parent ca8959d85d
commit 1f853337a1
1 changed files with 280 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

299
README.md
View File

@ -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,27 +56,28 @@ 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 |
| -----------------: | --------------: | ---------: |
| 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 |||
```
@ -114,12 +124,13 @@ Code above would be parsed as:
</table>
#### 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 :|||
|:------ |:------ |:-------- |
| : Easy Multiline : |||
| :----- | :----- | :------ |
| Apple | Banana | Orange \
| Apple | Banana | Orange \
| Apple | Banana | Orange
@ -156,6 +167,7 @@ Code above would be parsed as:
</table>
#### Headerless
Table header can be eliminated.
```markdown
@ -258,18 +270,19 @@ Code above would be parsed as:
</table>
#### Cell Alignment
Markdown table syntax use colons ":" for forcing column alignment.
Therefore, here we also use it for foring cell alignment.
Table cell can be set alignment separately.
```
|: Fruits \|\| Food :|||
|:-------- |:-------- |:------------ |
| Apple |: Apple :| Apple \
```markdown
| : Fruits \|\| Food : |||
| :--------- | :-------- | :-------- |
| Apple | : Apple :| Apple \
| Banana | Banana | Banana \
| Orange | Orange | Orange |
|: Rowspan is 4 :|| How's it? |
| : Rowspan is 4 : || How's it? |
|^^ A. Peach || 1. Fine :|
|^^ B. Orange ||^^ 2. Bad |
|^^ C. Banana || It's OK! |
@ -309,22 +322,79 @@ Rowspan is 4
</tbody>
</table>
#### 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:
<table>
<thead>
<tr>
<th align="center" colspan="3">MathJax || Image
</tr>
</thead>
<tbody>
<tr>
<td align="left">Apple<br>Banana<br>Orange</td>
<td align="center">Apple<br>Banana<br>Orange</td>
<td align="left">Apple<br>Banana<br>Orange</td>
</tr>
<tr>
<td align="center" rowspan="4" colspan="2">
Rowspan is 4
<br>A. Peach
<br>B. Orange
<br>C. Banana
</td>
</tr>
<tr>
<td align="center">How's it?</td>
</tr>
<tr>
<td align="left">
<ol>
<li><img width="100" src="http://latex2png.com/pngs/82b913db54a9f303bed7197d11347d74.png"></img></li>
<li><img width="150" src="https://jekyllrb.com/img/octojekyll.png" title="An exemplary image"></img></li>
</ol>
</td>
</tr>
<tr>
<td align="left"><b>It' OK!</b></td>
</tr>
</tbody>
</table>
### 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
<script type="text/markdown">
# Hybrid HTML with Markdown is a not bad choice ^\_^
## Table Usage
| : 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! |
## PlantUML Usage
@startuml
Bob -> Alice : hello
@enduml
## Video Usage
![](https://www.youtube.com/watch?v=Ptk_1Dc2iPY)
</script>
```
### 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.