Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation for readability #140

Merged
merged 20 commits into from
Aug 22, 2021
Merged

Update documentation for readability #140

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
44b6e4f
Trial run with Grammarly
zhangchuck Aug 1, 2021
820e839
Removed reference to Markdown metadata
zhangchuck Aug 1, 2021
459580c
Update whats-marp.md
zhangchuck Aug 1, 2021
8987fe0
Update install.md
zhangchuck Aug 1, 2021
a049233
Fixed inaccuracy on LivePreview.
zhangchuck Aug 4, 2021
8bf606f
Switched recommend export back to PDF.
zhangchuck Aug 4, 2021
9edb8c0
Update fitting-header.md
zhangchuck Aug 4, 2021
74a4969
Update fragmented-list.md
zhangchuck Aug 4, 2021
94da84d
Update heading-divider.md
zhangchuck Aug 4, 2021
62c360d
Update install.md
zhangchuck Aug 19, 2021
5ef841a
Update fragmented-list.md
zhangchuck Aug 19, 2021
1f4b57a
Update how-to-write-slides.md
zhangchuck Aug 19, 2021
b827a43
Update math-typesetting.md
zhangchuck Aug 19, 2021
15c51a2
Copied Marpit documentation
zhangchuck Aug 20, 2021
2e981bc
Edits to image syntax
zhangchuck Aug 20, 2021
d2cb432
Update website/docs/introduction/install.md
zhangchuck Aug 20, 2021
a94bca9
Merge branch 'main' into main
zhangchuck Aug 20, 2021
fa946a5
Revert "Edits to image syntax"
zhangchuck Aug 20, 2021
a776be5
Revert "Copied Marpit documentation"
zhangchuck Aug 20, 2021
37e1dad
Formatted with prettier .eslintrc.js 96ms
zhangchuck Aug 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 47 additions & 47 deletions website/docs/guide/directives.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

### This is a stub page!

Marp has extended syntax called **"Directives"** to control theme, page number, header, footer, and so on.
Marp has an extended syntax called **"Directives"** to control theme, page number, header, footer, and other slide elements.

> The syntax of directives is inherited from [Marpit framework](https://marpit.marp.app/directives). Please note supported directives are different by each Marp tools.
> The syntax of directives is inherited from [Marpit framework](https://marpit.marp.app/directives). Please note that different directives are used by each Marp tool.

## Usage

The written directives will parse as [YAML](https://yaml.org/) format.
Marp parses directives as [YAML](https://yaml.org/).

### HTML comment

Expand All @@ -21,9 +21,9 @@ paginate: true

### Front matter

**YAML front matter** is a syntax often used for keeping metadata of Markdown in a lot of tools (e.g. [Jekyll site generator](https://jekyllrb.com/docs/front-matter/)). Marp has also supported front matter as the container to define directives.
Like many tools (e.g. [Jekyll site generator](https://jekyllrb.com/docs/front-matter/)), Marp uses **YAML front matter**. Directives can be defined in front matter.

It must be the first thing of Markdown, and between the dash rulers.
YAML front matter must be at the beginning of a Markdown document and enclosed by dashed rulers.

```markdown
---
Expand All @@ -32,46 +32,46 @@ paginate: true
---
```

Don't confuse to [the ruler for splitting slides](/docs/guide/how-to-write-slides#slides)! The actual slide contents would start after the ending ruler of front-matter.
Note that the dashed ruler is also used to indicate where Marp should [ split slides](/docs/guide/how-to-write-slides#slides). Marp uses the first two dashed rulers to indicate YAML front matter. Subsequent dashed rulers indicate slide breaks.

> TIP: Defining directives via front matter is exactly same meaning as setting directives by HTML comment at the first page. When the front matter syntax is not supported in your favorite Markdown editor, you can replace into HTML comment safely in the most cases.
> TIP: Defining directives in the front matter is equivalent to setting the directives using an HTML comment on the first page. Suppose your favorite Markdown editor does not support the front matter syntax. In that case, you can safely define the directive in an HTML comment instead.

## Type of directives

Marp directives consisted of two groups:
There are two types of Marp directives:

- **[Global directives](#global-directives)** - Setting for the whole of slide deck (e.g. `theme`, `size`)
- **[Local directives](#local-directives)** - Controlling the setting value per slide pages (e.g. `pagiante`, `header`, `footer`)
- **[Global directives](#global-directives)** - Controlling settings for the all slides (e.g. `theme`, `size`)
- **[Local directives](#local-directives)** - Controlling setting values for one slide (e.g. `paginate`, `header`, `footer`)

There is no difference how to define each directives, and you can mix definitions too. An only difference is how to consume the value.
You can define both directives in the same way. You can mix definitions too. The only difference is that some settings apply to all slides, and some apply to only one slide.

### Global directives

**Global directives** are settings for the whole of slide deck.
**Global directives** are settings for the entire slide deck.

| Name | Description |
| ---------------- | ---------------------------------------------------------------- |
| `theme` | [Set a theme name for the slide deck ▶️](/docs/guide/theme) |
| `theme` | [Set a theme for the slide deck ▶️](/docs/guide/theme) |
| `style` | Specify CSS for tweaking theme |
| `headingDivider` | [Specify heading divider option ▶️](/docs/guide/heading-divider) |
| `size` | Choose the slide size preset provided by theme |
| `title` | Set a title of the slide deck (for HTML export) |
| `description` | Set a description of the slide deck (for HTML export) |
| `url` | Set canonical URL for the slide deck (for HTML export) |
| `title` | Set the title of the slide deck (for HTML export) |
| `description` | Set the description of the slide deck (for HTML export) |
| `url` | Set a canonical URL for the slide deck (for HTML export) |
| `image` | Set Open Graph image URL (for HTML export) |
| `marp` | Set whether or not enable Marp feature in VS Code |

Marp will recognize only the last defined value if you set the value for a same global directive many times in multiple HTML comments.
If you set the same global directive multiple times, Marp will use the last defined value.

### Local directives

**Local directives** are settings for each slide pages.
**Local directives** are settings for a specific slide.

| Name | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `paginate` | [Show page number on the slide if set `true` ▶️](#page-number) |
| `header` | [Specify the content of slide header ▶️](#header-and-footer) |
| `footer` | [Specify the content of slide footer ▶️](#header-and-footer) |
| `paginate` | [Show page number on the slide if set to `true` ▶️](#page-number) |
| `header` | [Specify the content of the slide header ▶️](#header-and-footer) |
| `footer` | [Specify the content of the slide footer ▶️](#header-and-footer) |
| `class` | Set [HTML `class` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) for the slide element `<section>` |
| `backgroundColor` | Set [`background-color` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) of the slide |
| `backgroundImage` | Set [`background-image` style](https://developer.mozilla.org/en-US/docs/Web/CSS/background-image) of the slide |
Expand All @@ -82,9 +82,9 @@ Marp will recognize only the last defined value if you set the value for a same

#### Inheritance

If not set the local directive explicit in a slide, **the setting value of local directives for the slide will be inherited from previous slide**. In other words, defined local directives will apply to the defined page and following pages.
Slides will inherit setting values of local directives from the immediately previous slide **unless** a local directive is explicitly set for the current slide. In other words, defined local directives will apply to both the defined page and subsequent pages.

For example, this Markdown is defining `backgroundColor` directive at the second page, and the third page will use the inherited color.
For example, the Markdown for this set of slides defines the `backgroundColor` directive on the second page. Because subsequent pages inherit local directives, the third page will also have the same color.

```markdown
# Page 1
Expand All @@ -97,13 +97,13 @@ Go to next page :arrow_right:

# Page 2

## This page has lightblue background.
## This page has a light blue background.

---

# Page 3

## This page also has the same background.
## This page also has the same light blue background.
```

```markdown:marp
Expand All @@ -117,20 +117,20 @@ Go to next page :arrow_right:

# Page 2

## This page has lightblue background.
## This page has a light blue background.

---

# Page 3

## This page also has the same background.
## This page also has the same light blue background.
```

#### Scoped local directives

To set specific value of local directives only to the current page, add the underscore prefix `_` to the name of directives.
If you want a local directive to apply only to the current page, add the underscore prefix `_` to the name of directives.

The value of scoped directive will be given priority over the inherited value from previous, and will not inherit to following pages.
The value of a scoped directive will be given priority over an inherited value, and subsequent pages will not inherit the value of the scoped directive.

```markdown
<!-- color: red -->
Expand All @@ -145,7 +145,7 @@ This page has red text.

# Page 2

This page has blue text, specified by scoped local directive.
This page has blue text, specified by a scoped local directive.

---

Expand All @@ -167,7 +167,7 @@ This page has red text.

# Page 2

This page has blue text, specified by scoped local directive.
This page has blue text, specified by a scoped local directive.

---

Expand All @@ -176,7 +176,7 @@ This page has blue text, specified by scoped local directive.
Go back to red text.
```

The underscore prefix can add to all of local directives.
The underscore prefix can be added to any local directives.

#### Diagram

Expand All @@ -188,18 +188,18 @@ The underscore prefix can add to all of local directives.

## Page number

To add page number to the slide, set **`paginate`** local directive as `true`.
To add page number to the slide, set the **`paginate`** local directive to `true`.

```markdown
<!-- paginate: true -->

You can see a page number of the slide in lower right.
You can see the slide number in the lower right.
```

```markdown:marp
<!-- paginate: true -->

You can see a page number of the slide in lower right.
You can see the slide number in the lower right.

<style>
@keyframes point {
Expand All @@ -218,11 +218,11 @@ You can see a page number of the slide in lower right.
</style>
```

Refer to [theme guide](/docs/guide/theme) for the detail of how to style a page number.
Refer to [theme guide](/docs/guide/theme) for details on how to style a slide number.

### Skip pagination in the title slide

Just move a definition of `paginate` directive to an inside of a second page.
Just move the definition of the `paginate` directive to the second slide.

```markdown
# Title slide
Expand All @@ -231,7 +231,7 @@ Just move a definition of `paginate` directive to an inside of a second page.

<!-- paginate: true --->

## Start pagination from this page.
## Start pagination from this slide.
```

```markdown:marp
Expand All @@ -241,7 +241,7 @@ Just move a definition of `paginate` directive to an inside of a second page.

<!-- paginate: true --->

## Start pagination from this page.
## Start pagination from this slide.

<style scoped>
@keyframes point {
Expand All @@ -260,7 +260,7 @@ Just move a definition of `paginate` directive to an inside of a second page.
</style>
```

Or you also can use [scoped directive](#scoped-local-directives) to disable pagination in the title slide.
You can also use [scoped directive](#scoped-local-directives) to disable pagination in the title slide.

```markdown
---
Expand All @@ -272,12 +272,12 @@ _paginate: false

---

## Start pagination from this page.
## Start pagination from this slide.
```

## Header and footer

Use **`header`** and **`footer`** local directive to add headers and footers to slides.
Use **`header`** and **`footer`** local directives to add headers and footers to slides.

```markdown
<!--
Expand Down Expand Up @@ -328,11 +328,11 @@ footer: Footer content
</style>
```

Refer to [theme guide](/docs/guide/theme) for the detail of how to style header and footer.
Refer to [theme guide](/docs/guide/theme) for details on how to style header and footer.

### Markdown formatting

You can contain inline Markdown formatting (italic, bold, inline image, etc) into header and footer like this:
You can use inline Markdown formatting (italic, bold, inline image, etc) in header and footer like this:

```markdown
---
Expand All @@ -341,11 +341,11 @@ footer: '![image](https://example.com/image.jpg)'
---
```

It may require to wrap the content by (double-)quotes to make directives parsable as valid YAML.
To make directives parsable as valid YAML, you can wrap content with (double-)quotes.

### Reset header and footer

Set an empty string value to directives to reset header and footer in the middle of slides.
Set the value of a directive to an empty string value to reset the header and footer in the middle of the slide deck.

```markdown
---
Expand Down Expand Up @@ -389,4 +389,4 @@ footer: ''

## Editor integration

<!-- By using **Marp for VS Code**, you can peek -->
<!-- By using **Marp for VS Code**, you can preview -->
6 changes: 3 additions & 3 deletions website/docs/guide/fitting-header.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Fitting header

When `<!--fit-->` comment has contained in the content of headings, it will be scaled to fit onto the slide size.
When the `<!--fit-->` comment is placed in a heading, the heading will be scaled to fit onto a single line.

```markdown
# <!-- fit --> Fitting header
Expand All @@ -10,15 +10,15 @@ When `<!--fit-->` comment has contained in the content of headings, it will be s
# <!-- fit --> Fitting header
```

The syntax is similar to [Deckset's `[fit]` keyword](https://docs.decksetapp.com/English.lproj/Formatting/01-headings.html), but Marp uses HTML comment to hide a keyword when rendered Markdown as the document.
The syntax is similar to [Deckset's `[fit]` keyword](https://docs.decksetapp.com/English.lproj/Formatting/01-headings.html), but Marp uses an HTML comment to hide the keyword when the Markdown is rendered.

> This feature is inherited from [Marp Core](https://github.com/marp-team/marp-core).

## Examples

### Takahashi-style

You can easily make [Takahashi-style](https://en.wikipedia.org/wiki/Takahashi_method) slides like [Big](https://github.com/tmcw/big) presentation system by using fitting header. Combination with [heading divider](/docs/guide/heading-divider) will give the best efficiency for creating the deck.
You can efficiently make [Takahashi-style](https://en.wikipedia.org/wiki/Takahashi_method) slides like the [Big](https://github.com/tmcw/big) presentation system by using the fitting header. Combining fitting headers with the [heading divider](/docs/guide/heading-divider) directive will allow you to write one slide per line.

```markdown
---
Expand Down
14 changes: 7 additions & 7 deletions website/docs/guide/fragmented-list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Fragmented list

Marp recognizes some uncommon list markers as the item of **fragmented list** (also known as incremental list, build animation) for appearing contents one by one.
Marp uses some uncommon list markers to denote a **fragmented list** (also known as an incremental list or builds), which allows list content to appear incrementally.

Fragmented list is _only available in the exported HTML_. Please note PDF and PPTX will not reproduce animation.
Fragmented lists are _only available if you export to HTML_. If you export to PDF and PPTX, the fragmented list will be rendered as a normal list.

> We recommend to make a careful decision whether using fragmented list. This is surely useful to focus audience's interests into the last displayed item. However, keep in mind that may bring confusion by what there are hidden items at the same time. Some articles are pointing out that build animation should never use in the presentation. (e.g. [Presentation Rules](http://www.jilles.net/perma/2020/06/05/presentation-rules.html))
> Be careful when using fragmented lists. While fragmented lists can help focus the audience's attention on the last displayed item, they may also create confusion about hidden items. Some articles recommend never using builds (e.g. [Presentation Rules](http://www.jilles.net/perma/2020/06/05/presentation-rules.html)).

## For bullet list
## For bullet lists

CommonMark allows `-`, `+`, and `*` as the character of [bullet list markers](https://spec.commonmark.org/0.29/#bullet-list-marker). Marp will parse as the fragmented list if you are using `*` as the marker.
CommonMark's bullet list markers are `-`, `+`, and `*` (https://spec.commonmark.org/0.29/#bullet-list-marker). If you use `*` as the marker, Marp will parse the list as a fragmented list.

<!-- prettier-ignore-start -->

Expand All @@ -32,7 +32,7 @@ CommonMark allows `-`, `+`, and `*` as the character of [bullet list markers](ht

## For ordered list

CommonMark's [ordered list marker](https://spec.commonmark.org/0.29/#ordered-list-marker) must have `.` or `)` after digits. Marp will parse as fragmented list if you are using `)` as the following character.
CommonMark's [ordered list marker](https://spec.commonmark.org/0.29/#ordered-list-marker) must have `.` or `)` after digits. If you use `)` as the following character, then Marp will parse the ordered list as a fragmented list.

<!-- prettier-ignore-start -->

Expand All @@ -56,4 +56,4 @@ CommonMark's [ordered list marker](https://spec.commonmark.org/0.29/#ordered-lis

> These are inherited from [Marpit framework](https://marpit.marp.app/fragmented-list).
>
> [The syntax just indicates that the list would be fragmented](https://marpit.marp.app/fragmented-list?id=rendering). A rendering result would be same as normal list if tools that are integrated with Marp did nothing. In the official toolset, [Marp CLI](https://github.com/marp-team/marp-cli)'s default HTML template `bespoke` can reproduce fragmented list as the step animation.
> [This syntax only indicates that the list _should_ be fragmented](https://marpit.marp.app/fragmented-list?id=rendering). However, this list would be rendered as a normal list if the tools that are integrated with Marp did nothing with the syntax. In the official toolset, [Marp CLI](https://github.com/marp-team/marp-cli)'s default HTML template `bespoke` can reproduce a fragmented list as a build animation.
Loading