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

[request] title-less admonitions #10958

Closed
2bndy5 opened this issue Nov 4, 2022 · 2 comments
Closed

[request] title-less admonitions #10958

2bndy5 opened this issue Nov 4, 2022 · 2 comments

Comments

@2bndy5
Copy link

2bndy5 commented Nov 4, 2022

It may be desirable to admonition a block of text without an attention-distracting/confusing title. I say "attention-distracting/confusing title" because

  1. A specific fixed title may not always match the purpose for admonishing text. (confusing)
  2. A title may be too much for accenting the minor importance of some text (distracting)

Proposed Implementation

Offer a new option for admonitions called no-title. This is to allow using the color and styling that a theme assigns to an admonition, but forgo the extra styling needed for the title. For example:

.. seealso::
    :no-title:

    Check out these interesting uses.

then adjust the BaseAdmonition.option_spec and implement the no-title option in run() accordingly.

The translated titles used in the overwritten visitors (for specific admonitions) can be moved into the directive's run() instead of passing the extra kwarg name to the generic visit_admonition(), unless there's a good reason to keep theme there.

Alternatives Considered

It may be prudent to change the generic admonition directive (in docutils) to use optional_arguments = 1 and final_argument_whitespace = True. The side-effect of this seems to mandate a blank-line between the directive's invocation and the directive's content, otherwise, the content gets misinterpreted as part of the arguments.

Additional context

This idea was born from porting mkdocs-material to sphinx-immaterial. With the mkdocs admonition plugin, the title is optional. A demonstration can be seen here.

In sphinx-immaterial theme, we provide a special directive that doesn't use any specific admonition (relies on the class option for CSS styling) as documented here. It is directly based on the docutils generic admonition but uses 1 optional argument instead of 1 required argument.

@jdillard
Copy link
Contributor

jdillard commented Nov 6, 2022

This seems to be a duplicate of #10713, I would add to the conversation there.

@2bndy5
Copy link
Author

2bndy5 commented Nov 6, 2022

Nice I didn't see that one. I'll close this and discuss there. Thanks!

@2bndy5 2bndy5 closed this as completed Nov 6, 2022
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Dec 7, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants