# Writing Content

## Writing Content

**Files:** any `.md` or `.mdx` file in `src/content/` · **Skill level:** Beginner

### Markdown In Fields
Most text fields in section files accept inline Markdown: `**bold**`, `*italic*`, and `[links](/pricing/)`. The comment next to a field says when it does ("Markdown works", "inline Markdown works"). A few fields give Markdown a special look:

| Where                                   | Write                         | Result                                           |
| --------------------------------------- | ----------------------------- | ------------------------------------------------ |
| Hero and page header `title`            | `Run your *team* from one board` | The word in Instrument Serif italic, in an outlined pill |
| Intro section `statement` (`/home-3/`)  | `your team **plans** the work` | The word in a pastel pill                       |
| Any title                               | `Line one <br /> line two`    | A forced line break (use sparingly; check phones) |

### Page And Entry Bodies
Blog posts, changelog releases, integrations, careers roles, and text pages have a **body** below the frontmatter, written in Markdown:

```md
## A heading

A paragraph with **bold** text and a [link](/features/).

- A list item
- Another one

> A quote.

![Alt text](/images/gallery/1.jpg)
```

- Start with `##` headings: the page title is already the `#` heading.
- On text pages, `##` and `###` headings build the "On this page" card (`[settings.markup.tableOfContents]` in `config.toml`).
- External links open in a new tab automatically.
- Images in the body are served from `public/`: `/images/gallery/1.jpg` is `public/images/gallery/1.jpg`.

### Shortcodes In MDX
Rename a post, release, integration, role, or text page from `.md` to `.mdx` to use these components in its body, without any import:

| Shortcode     | Example                                                                 |
| ------------- | ----------------------------------------------------------------------- |
| `Callout`     | `<Callout type="tip" title="Good to know">Text</Callout>` (`note`, `tip`, `warning`, `danger`) |
| `Notice`      | `<Notice type="info">Text</Notice>` (`info`, `warning`, `success`, `error`) |
| `Button`      | `<Button label="Start free" url="/signup/" variant="fill" />`           |
| `Accordion`   | `<Accordion label="Question?" group="faq">Answer</Accordion>`           |
| `Tabs`, `Tab` | `<Tabs><Tab name="Board">…</Tab><Tab name="List">…</Tab></Tabs>`        |
| `Steps`       | `<Steps>` around a numbered list                                        |
| `ListCheck`   | A list with check marks                                                 |
| `Kbd`         | Keyboard keys, for example `<Kbd keys={["⌘", "K"]} />`                  |
| `CodeTabs`    | Several code examples in tabs                                           |
| `FileTree`    | A folder tree                                                           |
| `ImageList`, `ImageItem` | A row of images                                              |
| `VideoInline` | An embedded YouTube or Vimeo video                                      |

The components live in `src/layouts/shortcodes/`; each file has a usage comment at the top.

<Aside type="caution">
  In `.mdx` files, `{`, `}`, and `<` have a meaning. Put text that contains
  them in backticks, or the build fails on that line.
</Aside>

### Code Blocks
Fenced code blocks get syntax colors, a title bar, and a copy button:

````md
```bash
npm run build
```
````

`[settings.markup.codeBlocks] theme` in `config.toml` picks `auto` (light code on light pages) or `dark`.

### Writing Tips For Taskly
- **Keep labels inside mockups short.** The dashboard, calendar, chat bubbles, task cards, annotations, and comment pins have fixed sizes. Two to four words fit best.
- **Write both languages.** Every change in `english/` needs its twin in `french/`, unless you turned French off.
- **Keep the comments.** The `#` comments in content files document every option. Your assistant and future you rely on them.
- **Use the sample markers.** Files and fields with sample data (ratings, reviews, prices, numbers, people) say so in a comment. Search for "Sample" to find what is left to replace.

### Do It With AI
```text
Rewrite the copy of [FILE] for my product, keeping every key, list length, and option. Keep labels
inside product mockups (chat messages, task titles, annotations, comment pins) under 5 words.
Keep *word* markers in titles on one or two words. Then translate the result into the matching
french/ file.
```