Skip to content

Commit 8d35ced

Browse files
jefBinomedjefBinomed
committed
docs: add documentation
1 parent 0120ceb commit 8d35ced

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+1542
-137
lines changed

‎README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,78 @@
66

77
<p align="center">
88
<a href="https://github.com/TalkControl/talk-control-revealjs-extensions/actions"><img src="https://github.com/TalkControl/talk-control-revealjs-extensions/actions/workflows/main.yml/badge.svg" alt="Build Status"></a>
9+
<a href="https://www.npmjs.com/package/talk-control-revealjs-extensions"><img src="https://img.shields.io/npm/v/talk-control-revealjs-extensions.svg" alt="NPM version"></a>
910
<a href="https://github.com/TalkControl/talk-control-revealjs-extensions/blob/main/LICENSE"><img src="https://img.shields.io/github/license/TalkControl/talk-control-revealjs-extensions" alt="License"></a>
1011
</p>
1112

1213
## About TalkControl
1314

1415
TalkControl aims to provides an easy to use extensions for anyone wanted to create slides with [reveal.js](https://github.com/hakimel/reveal.js).
16+
17+
You can preview it here : https://talk-control-revealjs-extensions.netlify.app/
18+
19+
## Features
20+
21+
Talk Control adds numerous out-of-the-box features:
22+
23+
### Core Extensions
24+
25+
- **Config UI** : An interface accessible with the `C` key to change themes, presentation types, and languages on the fly.
26+
- **Theming** : Applies and manages your presentation's themes.
27+
- **Internationalization (i18n)** : Multi-language support for your slides.
28+
- **Templates** : Propose diferent templates usable : transitions, speakers, ...
29+
- **Helpers** : Severals helpers likes positions, margins, backgrounds, ...
30+
- **Multiple Columns** : Create complex layouts with multiple columns.
31+
- **Copy to Clipboard** : Adds the ability to copy the content of code blocks.
32+
33+
### Markdown Extensions
34+
35+
- **Admonitions**: Stylized information blocks (note, warning, etc.).
36+
- **Icons**: Easily integrate icons (Feather Icons, Font Awesome, etc.).
37+
- **QR Codes**: Generate QR Codes directly in your slides.
38+
- **Backgrounds via Markdown**: Change a slide's background directly from your Markdown file.
39+
- **Columns via Markdown**: Define column layouts with a simple syntax.
40+
41+
## How to
42+
43+
See [How to](./docs/how-to.md)
44+
45+
## Development
46+
47+
To contribute to the project, follow these steps:
48+
49+
1. **Clone the repository:**
50+
51+
```bash
52+
git clone https://github.com/TalkControl/talk-control-revealjs-extensions.git
53+
cd talk-control-revealjs-extensions
54+
```
55+
56+
2. **Install dependencies:**
57+
58+
```bash
59+
npm install
60+
```
61+
62+
3. **Start the development server:**
63+
64+
```bash
65+
npm run start
66+
```
67+
68+
This will start a server with the demo presentation.
69+
70+
4. **Build for production:**
71+
72+
```bash
73+
npm run build
74+
```
75+
76+
5. **Run tests:**
77+
```bash
78+
npm run test
79+
```
80+
81+
## License
82+
83+
This project is licensed under the [Apache 2](LICENSE) License.

‎demo/markdown/01-classics/20_transitions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ source: [unsplash](https://unsplash.com/fr/photos/couloir-en-beton-avec-applique
206206
# Code to produce / Markdown
207207

208208
```markdown
209-
<!-- .slide: class="transition txt-white" style="--tc-transition-color: cornflowerblue;" -->
209+
<!-- .slide: class="transition" style="--tc-transition-color: cornflowerblue;" -->
210210

211211
# Talk Control Theme
212212

@@ -228,7 +228,7 @@ source: [unsplash](https://unsplash.com/fr/photos/couloir-en-beton-avec-applique
228228
# Code to produce / Markdown
229229

230230
```markdown
231-
<!-- .slide: class="transition txt-white" style="--tc-transition-color: cornflowerblue; --tc-transition-line-color: darkorange;" -->
231+
<!-- .slide: class="transition" style="--tc-transition-color: cornflowerblue; --tc-transition-line-color: darkorange;" -->
232232

233233
# Talk Control Theme
234234

‎demo/markdown/03-layouts/20_multiple-columns.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,47 @@
44

55
##==##
66

7+
# Multiple columns
8+
9+
Due to some "magic" done by RevealJS engine, it's recommand to not use multiple columns with vertical slides.
10+
11+
Multiple columns with background and vertical slides won't work.
12+
13+
##==##
14+
15+
<!-- .slide: class="tc-multiple-columns" -->
16+
17+
##++##
18+
19+
# Column 1
20+
21+
Some content
22+
23+
##++##
24+
25+
##++##
26+
27+
# Column 2
28+
29+
Some content
30+
31+
##++##
32+
33+
##++##
34+
35+
# Column 3
36+
37+
Some content
38+
39+
##++##
40+
41+
##==##
42+
43+
<!-- .slide: class="whith-code" -->
44+
45+
# Code to produce / Markdown
46+
47+
```markdown
748
<!-- .slide: class="tc-multiple-columns" -->
849

950
##++##
@@ -29,6 +70,7 @@ Some content
2970
Some content
3071

3172
##++##
73+
```
3274

3375
##==##
3476

@@ -52,6 +94,32 @@ Some content
5294

5395
##==##
5496

97+
<!-- .slide: class="whith-code" -->
98+
99+
# Code to produce / Markdown
100+
101+
```markdown
102+
<!-- .slide: class="tc-multiple-columns" -->
103+
104+
##++## data-background="red"
105+
106+
# Column 1 with bg
107+
108+
Some content
109+
110+
##++##
111+
112+
##++## data-background="./assets/images/light_background.jpg" class="mask"
113+
114+
# Column 2 with image bg
115+
116+
Some content
117+
118+
##++##
119+
```
120+
121+
##==##
122+
55123
<!-- .slide: data-background="yellow" -->
56124

57125
# Vertical slide with bg (first)

‎demo/scripts/slides.js‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,7 @@ function schoolSlides(showType) {
1616
'00_intro.md',
1717
`${dir}/10_chapter1.md`,
1818
`${dir}/20_transitions.md`,
19-
!showType || showType === 'custom'
20-
? undefined
21-
: `${dir}/30_code_slides.md`,
19+
showType === 'custom' ? undefined : `${dir}/30_code_slides.md`,
2220
`${dir}/40_custom_bg_slides.md`,
2321
];
2422
}
@@ -59,10 +57,18 @@ function formation(showType) {
5957
return [
6058
//
6159
...schoolSlides(),
62-
...(!showType || showType === 'speakers' ? speakerSlides() : []),
63-
...(!showType || showType === 'layouts' ? layoutsSlides() : []),
64-
...(!showType || showType === 'helpers' ? helpersSlides() : []),
65-
...(!showType || showType === 'tools' ? toolsSlides() : []),
60+
...(!showType || showType === 'on-stage' || showType === 'speakers'
61+
? speakerSlides()
62+
: []),
63+
...(!showType || showType === 'on-stage' || showType === 'layouts'
64+
? layoutsSlides()
65+
: []),
66+
...(!showType || showType === 'on-stage' || showType === 'helpers'
67+
? helpersSlides()
68+
: []),
69+
...(!showType || showType === 'on-stage' || showType === 'tools'
70+
? toolsSlides()
71+
: []),
6672
]
6773
.filter((element) => element !== undefined)
6874
.map((slidePath) => {

‎docs/admonition.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Admonitions
2+
3+
Admonitions are special blocks of text that highlight information, such as notes, tips, or warnings. Talk-Control provides a simple syntax to create them in your Markdown files.
4+
5+
## Usage
6+
7+
To create an admonition, use the following syntax, starting and ending with `!!!`:
8+
9+
```markdown
10+
!!! type
11+
Your content here. It can span multiple lines.
12+
!!!
13+
```
14+
15+
- `type`: The type of admonition you want to create.
16+
17+
For example:
18+
19+
```markdown
20+
!!! note
21+
This is a note. It contains some important information.
22+
!!!
23+
```
24+
25+
This will be rendered as a styled block with a "📝 Note" title.
26+
27+
## Available Types
28+
29+
Here is a list of the pre-configured admonition types you can use:
30+
31+
| Type | Rendered Title |
32+
| ----------- | -------------- |
33+
| `abstract` | 📋 Abstract |
34+
| `info` | ℹ️ Info |
35+
| `tip` | 💡 Tip |
36+
| `note` | 📝 Note |
37+
| `success` | ✅ Success |
38+
| `question` | ? Question |
39+
| `warning` | ⚠️ Warning |
40+
| `failure` | ❌ Failure |
41+
| `danger` | 🔥 Danger |
42+
| `important` | ❗ Important |
43+
| `bug` | 🐞 Bug |
44+
| `example` | 💻 Example |
45+
| `quote` | 💬 Quote |
46+
47+
![](./imgs/admonition.png)
48+
49+
## Custom Admonitions
50+
51+
If the predefined types don't fit your needs, you can create a custom admonition.
52+
53+
### Custom Title and Icon
54+
55+
Use the `custom` type and provide a title/icon using the `tc-admonition-type` attribute.
56+
57+
```markdown
58+
!!! custom tc-admonition-icon="🐼 Panda Facts"
59+
Pandas are native to central China.
60+
!!!
61+
```
62+
63+
### Custom Color
64+
65+
You can also specify a custom color for the left border and the title using the `tc-admonition-color` attribute. The value should be a valid CSS color.
66+
67+
```markdown
68+
!!! custom tc-admonition-type="🕶️ Custombis" tc-admonition-color="#d7be00"
69+
Custom and custom color
70+
!!!
71+
```
72+
73+
![](./imgs/admonition-custom.png)
74+
75+
## Use comment syntax
76+
77+
To use revealJS comment syntax you can use the following code
78+
79+
```md
80+
Some info block
81+
82+
<!-- .element: class="admonition info" -->
83+
84+
Custom and custom color
85+
86+
<!-- .element: class="admonition custom" data-admonition-icon="🕶️ Custombis" style="--tc-admonition-bg-color:#d7be00;" -->
87+
```

‎docs/backgrounds.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Backgrounds helpers
2+
3+
In addition to the "revealJS way" to set a background for a slide (`<!-- .slide: data-background="...." -->`), you can use a new syntax:
4+
5+
```md
6+
![](./assets/images/light_background.jpg 'tc-bg')
7+
```
8+
9+
![](./imgs/background-new.png)
10+
11+
You can also use colors (color name, rgb, hash)
12+
13+
```md
14+
![](red 'tc-bg')
15+
```
16+
17+
![](./imgs/background-new-color.png)
18+
19+
This will preserve classes put on the slide element:
20+
21+
```md
22+
<!-- .slide: class="mask transition" -->
23+
24+
# Use background but preserve meta of reveal (.slide)
25+
26+
![](./assets/images/dark_background.jpeg 'tc-bg')
27+
```
28+
29+
![](./imgs/background-new-preserve.png)

0 commit comments

Comments
 (0)