@infosupport/kc-cli v6.3.0
kc-cli
The one-stop-shop for @infosupport employees to create and serve slick Reveal.js presentations.
Install
Both local and global installations are possible. Global is easiest and therefore the recommended approach.
Global
This has the advantage that you only have to install it and you're ready to go.
npm install --global @infosupport/kc-cli # Windows
npm install --global @infosupport/kc-cli --unsafe-perm=true # Linux
Local
With this, you are free to choose when you want to upgrade to newer versions of the CLI with, for example, a new corporate design.
You will have to make it an npm
project.
npm init --yes
npm install @infosupport/kc-cli # Windows
npm install @infosupport/kc-cli --unsafe-perm=true # Linux
Then, in the package.json
, add a start script:
{
"scripts": {
"start": "kc serve"
}
}
Usage
To get a setup quick and easy, run kc init
. After choosing the "demo" example, it generates a folder structure similar to this:
├── css
│ └── custom.css
├── description.md
├── description.nl.md
├── kc.json
├── labSolutions
├── labs
│ ├── lab01.md
│ ├── lab02.md
│ └── starter
│ └── readme.md
├── learning-goals.md
├── slides
│ ├── 00-intro
│ │ ├── 01-title.md
│ │ ├── 02-agenda.md
│ │ └── 03-about.md
│ ├── 01-markdown-basics
│ │ ├── 01-title.md
│ │ ├── 02-text.md
│ └── 99-wrap-up
│ ├── 01-title.md
│ ├── 02-best-practices.md
│ ├── 97-questions.md
│ ├── 98-end.md
│ └── 99-logo.md
└── web-components
└── my-component
├── my-component.js
├── my-component.styles.js
└── my-component.template.js
From there, use your favorite text editor (e.g., Visual Studio Code) to change the content of the slides, modify the custom CSS, etc.
A couple of notes on the project folders:
/slides
contains subdirectories for each chapter/module and holds markdown files (the slides) inside those subfolders./slides
is the only required folder for a minimal setup/css
is for customizing the style of your presentation using CSS/assets
is for holding assets like images and videos. You can also name this folder something else like/img
/web-components
is for your own custom, interactive presentation widgets. It's advanced stuff. Scroll down for more information./labs
is where you put the labs.
To view your presentation:
kc serve # for global installations
npm start # for local installations
Serve
option | description |
---|---|
kc serve | serve presentation from current directory on default port |
kc serve -o | open presentation in default browser |
kc serve -o -f java | open presentation in default browser for flavor 'java' (see flavors) |
kc serve -p | use random port |
kc serve -p <port> | use specified <port> |
kc serve --nolive | disable live reload |
Both the presentation as the labs are served. When you run kc serve
you will see message like this:
Presentation url: http://localhost:15000, labs url: http://localhost:15000/labs, learning goals url: http://localhost:15000/learning-goals
You can open one of these URLs in chrome.
Note: Firefox is supported, but Chrome presentations look crispier because revealjs uses proprietary chrome features.
This will export your slides to PDF using Decktape and pdf-lib. First, Decktape reads all the presentation slides and uses pdf-lib to generate a PDF where every page is a slide. With a bit of custom code, this PDF is transformed into a PDF that fits our corporate design.
kc print
will serve
the presentation itself.
option | description |
---|---|
kc print | print presentation to PDF |
kc print --output [filename] | use specified filename |
kc print --module [module number] | generate a PDF for a specific module |
kc print --per-module | generate a PDF for each module. The module titles will be used for filenames |
kc print --flavor java | generate a PDF for a specific flavor (see flavors) |
kc print --no-labs | skip generating a PDF for the labs. |
Linting
option | description |
---|---|
kc lint | diagnose issues for when the presentation isn't running as it should |
Other commands
This is a list of other commands that are available:
command | description |
---|---|
kc build | Build standalone applications. Currently, only learning goals are supported. |
kc extract | Extract content for the course description on the website. |
kc pack | Print, build, extract and package a presentation with labs and lab solutions. |
Corporate identity
By default, the corporate identity is applied to every slide. Certain slides can receive specific theming.
- For the welcoming slide, often the very first slide, add
<!-- .slide: class="is-welcome" -->
. - For a new chapter, add
<!-- .slide: class="is-module" -->
. - For the closing slide, the very last slide, add
<!-- .slide: class="is-closing" -->
. - For additional emphasis, for example a new topic inside a chapter, add
<!-- .slide: class="is-fancy1" -->
through<!-- .slide: class="is-fancy3" -->
. - To add a lab slide, add
<!-- .slide: class="is-lab" -->
. - To disable theming, add
<!-- .slide: class="is-empty" -->
.
Layout and styling
The CLI offers a few options out of the box:
kc-flex
to turn an element into a flex containerkc-columns
to turn an element into a flex container where all its children have an equal widthkc-grid
to apply a grid to an elementkc-gap1
throughkc-gap5
to create a gap between flex/grid itemskc-table
to apply alternating row colors to a tablekc-smaller
to decrease font sizekc-smallest
to decrease font size furtherkc-left
andkc-right
for floating left/right- or alignment with
margin
for tables
- or alignment with
Apply these classes with a bit of HTML
<div class="kc-flex">
- item 1
- item 2
- item 3
</div>
or with special comments
![Example image](img/example.png)
<!-- .element: class="kc-right" -->
See the example/
folder for exact implementations.
Web Components
With Reveal.js, we can leverage Web Components to make slides more awesome. Right now, you can use these components out-of-the-box.
Note that web components are not natively supported in IE and this CLI is quite comfortable with not making any effort whatsoever to make it work in those browsers.
web component | description |
---|---|
<kc-timeline events='[{ "year": 2019, "caption": "cool stuff", "description": "detailed explanation of cool stuff" }]'> | A graphical visualization of a timeline. |
<npm-weekly-downloads package="@stryker-mutator/core"></npm-weekly-downloads> | Retrieves the number of weekly downloads for an npm package. Also caches the number in the session storage as to unburden npm's servers |
If you have (created or not) a web component that should be in this list, please let us know.
Customization and fun stuff
- The free version of font awesome v5 is included by default.
- Add your own custom CSS by creating a folder
css
and placing.css
files in there. - Add your own web components by creating a folder
web-components
with subfolders for every components. The main.js
file should be the same name as the folder it's in.
Example folder structure:
|-- css
|-- ...
|-- slides
|-- ...
|-- web-components
|-- cool-graph
|-- cool-graph.js
|-- cool-graph.html.js
|-- cool-graph.css.js
Flavors
It is possible to host multiple presentations from one master presentation. This is also called a 'monorepo' or 'polyglot' repository.
To get a setup quick and easy, run kc init
and choose the flavors
example.
It will generate the following structure:
├── kc.json
├── lab-solutions
│ ├── lab01-csharp
│ │ └── readme.md
│ └── lab01-java
│ └── readme.md
├── labs
│ ├── lab01-csharp.md
│ ├── lab01-java.md
│ ├── lab01-python.md
│ └── lab02-shared.md
└── slides
├── 00-intro
│ └── 01-title.md
├── 01-chapter-csharp
│ └── 01-title.md
├── 01-chapter-java
│ └── 01-title.md
├── 01-chapter-python
│ └── 01-title.md
├── 02-shared-chapter
│ ├── 01-title.md
│ ├── 02-specific-slide-csharp.md
│ ├── 02-specific-slide-java.md
│ ├── 02-specific-slide-python.md
│ ├── 03-shared-slide.md
│ ├── 04-only-python.md
│ ├── 04-shared-!python.md
│ └── 05-lab.md
└── 03-outro
└── 99-recap.md
This is an example of using 3 flavors: csharp
, java
and python
. Flavors names can be anything, they don't have to be programming languages.
Configuring flavors inside kc.json
The kc.json file is where you configure the flavors. The example looks like this:
{
"$schema": "https://unpkg.com/@infosupport/kc-cli/kc-schema.json",
"flavors": {
"csharp": { "trainingCode": "FLCS" },
"java": { "trainingCode": "FLJV" },
"python": { "trainingCode": "FLPY" }
}
}
Here, each flavor has a name ("csharp", "java" and "python" in this example) and a trainingCode
. The training code is used to base the pdf
name on when using kc print
or kc pack
and they should reflect the KC training code for the training.
Activating a flavor
When you run kc serve
with multiple flavors defined in the kc.json
file, you can choose which flavor to active using the ?flavor=flavorName
on the query string. It is also printed to the console:
Presentation has 3 flavor(s):
csharp: http://localhost:35943?flavor=csharp
java: http://localhost:35943?flavor=java
python: http://localhost:35943?flavor=python
Using serve
with --open
(or -o
) will open all the flavors in your default browser, or it will open a specific flavor of your choosing with --flavor java
(or -f java
).
Switch flavors
You can switch flavors mid-presentation using the c
button. This can be especially helpful when you're creating for multiple flavors at once.
Display / hide specifics
When using multiple flavors, slides are shown as usual, but there are ways to choose what to display on specific flavors:
- You can use flavored file names and directory names.
- Use a
01-chapter-flavorName
directory to create a chapter specific to a flavor. - Use a
01-chapter/01-slide-flavorName.md
markdown file for a specific flavor. - You can use multiple flavors:
01-chapter-flavor1-flavor2
. - Instead of
-flavorName
you can use-!flavorName
to exclude 1 flavor
- Use a
- Inside a shared markdown file:
- Code examples are automatically specific to the current flavor
- Use the
flavor-flavorName
andflavor-!flavorName
css classes to deviate inside text.
Examples:
Here are some useful examples:
The mocking framework we're going to use is <span class="flavor-java">mockito</span><span class="flavor-csharp">moq</span>
Installing this with:
```bash
dotnet add package moq
```
<!-- .element class="flavor-csharp" -->
```xml
<!-- <project><dependencies> -->
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<version>4.11.0</version>
<scope>test</scope>
</dependency>
<!-- </dependencies></project> -->
```
<!-- .element class="flavor-java" -->
Printing multiple flavors
When printing a presentation with multiple flavors, they are all printed by default. You can choose a specific flavor to print using --flavor flavorName
.
The kc-cli uses this naming scheme for pdfs:
[output]-<trainingCode>-[nr-chapterTitle].pdf
Where:
output
is the optional--output
parameter value.trainingCode
is the required training code associated with the flavor.nr-chapterTitle
nr and chapter title are the nr and name of the chapter when using--per-module
.
Logitech Spotlight
When you want to use your 'Logitech spotlight wireless presenter':
- press
>
or<
to browse between slides - remap "press and hold
>
or<
" with the Logitech Software to the ➡ and ⬅ keys. - press and hold
>
or<
to browse between chapters
The spotlight mode is meant to support the browse buttons for the 'Logitech spotlight wireless presenter'.\
The spotlight >
and <
buttons are hard-wired to the ➡ and ⬅ keys. By default, in reveal.js, these keys are mapped to 'next chapter' and 'previous chapter'.
In spotlight mode, the ➡ and ⬅ keys will get mapped to 'next slide' and 'previous slide'.\
Pressing and holding the >
and <
keys are not hard-wired and can be remapped with the Logitech Software.\
Known issues
None at the moment.
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
8 months ago
9 months ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago