Skip to content

docs: add docs for file imports #368

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.

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

Merged
merged 11 commits into from
Oct 14, 2024
69 changes: 69 additions & 0 deletions docs/tutorialkit.dev/src/content/docs/guides/creating-content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -144,3 +144,72 @@ src/templates
│ # Overrides "index.js" from "shared-template"
└── index.js
```

## Markdown and MDX Support

TutorialKit comes with built-in support for both Markdown and MDX, powered by Astro. This means you can leverage all Markdown and MDX features when creating lesson content. To explore the full capabilities, check out Astro's [Markdown support](https://docs.astro.build/en/guides/markdown-content/) and [MDX support](https://docs.astro.build/en/guides/integrations-guide/mdx/) documentation for more details.

### Callouts

Callouts are visual elements designed to highlight specific information or provide additional context within a document or user interface. They are ideal for drawing attention to important tips, warnings, and other key messages.

You can create callouts using the following types: `tip`, `info`, `warn`, `danger` and `success`.

```
:::info
Some info with some markdown `syntax` and a [`link`](https://tutorialkit.dev/).

Here's a normal [link](https://tutorialkit.dev/).
:::
```

![Content](../reference/images/theming-callout.png)

To customize the styles of a callout, check out the [theming reference](/reference/theming/#callouts).


### Code blocks

TutorialKit offers a comprehensive set of code block features powered by Expressive Code. It includes all core features, along with optional plugins like collapsible sections and line numbers. For a full overview, check out the [Expressive Code documentation](https://expressive-code.com/).

````txt
```js title="code.js" ins={4} del={5} {6} "greeting"
const greeting = 'Hello, World!';

// This is a comment
const added = 'This line was added';
const removed = 'This line was removed';
const highlighted = 'This line is highlighted';
```
````

```js title="code.js" ins={4} del={5} {6} "greeting"
const greeting = 'Hello, World!';

// This is a comment
const added = 'This line was added';
const removed = 'This line was removed';
const highlighted = 'This line is highlighted';
```

#### Importing files

In addition to Expressive Code features, you can import files from your code template `_files` and `_solution` folders using the file or solution shortcodes. These shortcodes insert the content of the specified file directly into your lesson content.

- `file` shortcode is used to reference files from the lesson `_files` or code template folder.
- `solution` shortcode is used to reference files from the lesson `_solution` folder.

For example, the following code will insert the content of the `box.css` file from the `_files` folder:

````md "file"
```file:/box.css
```
````

```css
.box {
width: 100px;
height: 100px;
background-color: red;
}
```
14 changes: 1 addition & 13 deletions docs/tutorialkit.dev/src/content/docs/reference/theming.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,22 +77,10 @@ The content refers to the main part of the lesson that contains the text and ima

### Callouts

Callouts are visual elements used to draw attention to specific information or provide additional context within a document or user interface. They are typically used to highlight important tips, warnings, or other types of messages.

For instanceof, here's an example of an info callout.
Customize the appearance of each callout type by adjusting its specific style tokens. Each callout includes tokens for elements such as text color, title color, icon color, background, code snippet color, and border color.

![Content](./images/theming-callout.png)

Callouts are created like this:

```
:::tip
This is a tip
:::
```

Valid callout names are `tip`, `info`, `warn` and `danger`.

#### Tip

| Token | Description |
Expand Down