You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It may be desirable to admonition a block of text without an attention-distracting/confusing title. I say "attention-distracting/confusing title" because
A specific fixed title may not always match the purpose for admonishing text. (confusing)
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.
The text was updated successfully, but these errors were encountered:
It may be desirable to admonition a block of text without an attention-distracting/confusing title. I say "attention-distracting/confusing title" because
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:then adjust the
BaseAdmonition.option_spec
and implement theno-title
option inrun()
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 kwargname
to the genericvisit_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
andfinal_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.The text was updated successfully, but these errors were encountered: