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.

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

Conversation

DanStuder
Copy link

The page only explained how to set the title of one specific callout block. I suggest adding a new section about changing titles in general, also explaining how to change the default titles, as I suspect other users will find that very useful too.

The page only explained how to set the title of one specific callout block. I suggest adding a new section about changing titles in general, also explaining how to change the default titles, as I suspect other users will find that very useful too.
@DanStuder DanStuder changed the title Add section about changing titles Documentation: Add section about changing titles for callout blocks Jan 23, 2025
@cderv
Copy link
Collaborator

cderv commented Jan 24, 2025

Thanks for the contribution.

I agree this is working and you can do this, so it is worth mentioning. Though, I am still unsure if we should document this way, because language option is really about language option for internationalization: https://quarto.org/docs/authoring/language.html

If we do document it for callout, we may need to document it for each element where this is applying.

This is also different API that for crossref, where we have dedicated option
https://quarto.org/docs/authoring/cross-reference-options.html
but also available through language option
https://github.com/quarto-dev/quarto-cli/blob/bf5bc5add450aa8a7c911d7162c28e1294f7631e/src/resources/language/_language.yml#L85-L95

So maybe we need a callout: key in configuration to change the style and appearance of all callouts.

Right now we only have some globals https://quarto.org/docs/authoring/callouts.html#customizing-appearance

callout-appearance: simple
callout-icon: false

But not per callout. So maybe we need something like

callout:
  note-appearance: simple
  note-icon: false
  important-title: Very Important

I'll think about this and discuss with the team.

@cderv
Copy link
Collaborator

cderv commented Jan 24, 2025

/deploy-preview

Copy link
Contributor

🚀 Deployed on https://deploy-preview-1555.quarto.org

Comment on lines +122 to +131
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"
```
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 !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants