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

Documentation: Add section about changing titles for callout blocks #1555

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Documentation: Add section about changing titles for callout blocks #1555

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
28 changes: 20 additions & 8 deletions docs/authoring/callouts.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,14 +68,6 @@ This is an example of a 'folded' caution callout that can be expanded by the use
:::
```

Note that above callout titles are defined by using a heading at the top of the callout. If you prefer, you can also specify the title using the `title` attribute. For example:

```markdown
::: {.callout-tip title="Tip with Title"}
This is a callout with a title.
:::
```

## Customizing Appearance

### Collapse
Expand Down Expand Up @@ -118,6 +110,26 @@ which appears as:
Using callouts is an effective way to highlight content that your reader give special consideration or attention.
:::

### Title

Note that above callout titles are defined by using a heading at the top of the callout. If you prefer, you can also specify the title using the `title` attribute. For example:

```markdown
::: {.callout-tip title="Tip with Title"}
This is a callout with a title.
:::
```
You can also change the default title of callout blocks for one page or the whole project, by adding the following lines to your documents yaml-header or your `_quarto.yaml` document respectively.

```markdown
language:
callout-note-title: "New note title"
callout-warning-title: "New warning title"
callout-important-title: "New important title"
callout-tip-title: "New tip title"
callout-caution-title: "New caution title"
```
Comment on lines +122 to +131
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So after discussion with the team, we prefer to take a sligthly different approach to documenting this:

  • Quarto documentation logic is right now to document each top language feature with its usually top level configuration key.
  • This means that any language: usage should be a in language section.
  • This doc is about callout and so should be about top level callout related options.

The proposal is the following:

  • We are missing a good documentation on language option available. So we'll add to our current language doc.
  • In that doc we could document better some usage for each specific feature, like here are the callout options.

So I'll add to the document language doc, and then we can link from callout part here to the correct callout language options.

In the future, we may come with a callout: top level option with a way to tweak option globally, but there is some challenge to make that good so that it works for any future feature too.

Thanks for your understanding, and thank you for this PR !


### Icons

In addition to controlling the appearance of the callout, you can also choose to directly suppress the icon by setting the global option in your document (or project) yaml:
Expand Down
Loading