🚀 Jekyll Spaceship 🚀
Jekyll plugin for Astronauts.
Requirements | Install | Usage | Credits | License
A Jekyll plugin to provide powerful supports for table, mathjax, plantuml, emoji, youtube, vimeo, dailymotion, etc.
💡 Tip: I hope you enjoy using this plugin. If you like this project, a little star for it is your way make a clear statement: My work is valued. I would appreciate your support! Thank you!
Table of Contents
- Requirements
- Installation
- Usage
- 1. Table Usage
- 1.1 Rowspan and Colspan
- 1.2 Multiline
- 1.3 Headerless
- 1.4 Cell Alignment
- 1.5 Cell Markdown
- 2. MathJax Usage
- 2.1 Performance Optimization
- 2.2 How to use?
- 3. PlantUML Usage
- 4. Video Usage
- 4.1 Youtube Usage
- 4.2 Vimeo Usage
- 4.3 DailyMotion Usage
- 5. Hybrid HTML with Markdown
- 6. Markdown Polyfill
- 6.1 Escape Ordered List
- 7. Emoji Usage
- Credits
- Contributing
- License
Requirements
- Ruby >= 2.3.0
Installation
Add jekyll-spaceship plugin in your site's Gemfile, and run bundle install.
gem 'jekyll-spaceship'
Add jekyll-spaceship to the gems: section in your site's _config.yml.
plugins:
- jekyll-spaceship
💡 Tip: Note that GitHub Pages runs in safe mode and only allows a set of whitelisted plugins. To use the gem in GitHub Pages, you need to build locally or use CI (e.g. travis, github workflow) and deploy to your gh-pages branch. Click here for more information.
Usage
1. Table Usage
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
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.
| 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:
| 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 FADH2 | 3 ATP | |
| 30–32 ATP | ||
Multiline
A backslash at end to join cell contents with the following lines.
This feature is contributed by Lucas-C.
| : 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:
| Easy Multiline | ||
|---|---|---|
| Apple Apple Apple |
Banana Banana Banana |
Orange Orange Orange |
| Apple Apple |
Banana Banana |
Orange Orange |
| Apple | Banana | Orange |
Headerless
Table header can be eliminated.
|--|--|--|--|--|--|--|--|
|♜| |♝|♛|♚|♝|♞|♜|
| |♟|♟|♟| |♟|♟|♟|
|♟| |♞| | | | | |
| |♗| | |♟| | | |
| | | | |♙| | | |
| | | | | |♘| | |
|♙|♙|♙|♙| |♙|♙|♙|
|♖|♘|♗|♕|♔| | |♖|
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.
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! |
Code above would be parsed as:
| Fruits || Food | ||
|---|---|---|
| Apple Banana Orange |
Apple Banana Orange |
Apple Banana Orange |
|
Rowspan is 4
A. Peach B. Orange C. Banana |
||
| How's it? | ||
| 1. Fine 2. Bad |
||
| It' OK! | ||
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.
| : 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? | ||
|
|
||
| It' OK! | ||
2. MathJax Usage
MathJax 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 setup for the reader
- 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
2.1 Performance optimization
At building stage, the MathJax engine script will be added by automatically checking whether there is a math expression in the page, this feature can help you improve the page performance on loading speed.
2.2 How to use?
Put your math expression within \$...\$
$ a * b = c ^ b $
$ 2^{\frac{n-1}{3}} $
$ \int\_a^b f(x)\,dx. $
3. PlantUML Usage
PlantUML 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:
```plantuml
Bob -> Alice : hello world
```
or
@startuml
Bob -> Alice : hello
@enduml
4. Video Usage
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:
Reference-style:
![][{reference}]
[{reference}]: {video-link}
For configuring video attributes (e.g, width, height), just adding query string to the link as below:
Youtube Usage
Vimeo Usage
DailyMotion Usage
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:
<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
</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.
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:
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.
7. Emoji Usage
GitHub-flavored emoji images and names would allow emojifying content such as: it's raining :cat:s and :dog:s!
Noted that emoji images are served from the GitHub.com CDN, with a base URL of https://github.githubassets.com, which results in emoji image URLs like https://github.githubassets.com/images/icons/emoji/unicode/1f604.png.
In any page or post, use emoji as you would normally, e.g.
I give this plugin two :+1:!
Code above would be parsed as:
I give this plugin two :+1:!
Credits
- Jekyll - A blog-aware static site generator in Ruby.
- MultiMarkdown - Lightweight markup processor to produce HTML, LaTeX, and more.
- markdown-it-multimd-table - Multimarkdown table syntax plugin for markdown-it markdown parser.
- jmoji - GitHub-flavored emoji plugin for Jekyll.
Contributing
Issues and Pull Requests are greatly appreciated. If you've never contributed to an open source project before I'm more than happy to walk you through how to create a pull request.
You can start by opening an issue describing the problem that you're looking to resolve and we'll go from there.
License
This software is licensed under the MIT license © JeffreyTse.