Giters

squidfunk / mkdocs-material

Documentation that simply works

Home Page:https://squidfunk.github.io/mkdocs-material/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Admonitions Formatting; Capitals and Multiple Worded Headers

GL513 opened this issue · comments

commented

Contribution guidelines

I've found a bug and checked that ...

  • ... the problem doesn't occur with the mkdocs or readthedocs themes
  • ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
  • ... the documentation does not mention anything about my problem
  • ... there are no open or closed issues that are related to my problem

Description

Admonitions formatting forces capitals. Admonitions do not allow for more than one word in header, and do not follow quotes.

Expected behaviour

When admonitions are placed in a document, the user should be able to capitalize as needed, and it shouldn't be forcing them to use capitals at the beginning of every header. Admonitions should also be able to have more than one word in header. User should be able to already enter more than one letter and mkdocs-material renders the whole line after !!! as the header. As another option, you could have quotes around the header phrase if it is more than one word, and quotes aren't required for one word.

Actual behaviour

Admonitions are currently being capitalized no matter what, there is no option to fix this easily.
Admonitions don't currently allow for more than one word after !!!, and even if this were possible, it may be considered hacky.

Steps to reproduce

  1. Create Test document for testing

  2. Go to index.md and paste in the following
    !!! "With quotes"

    Hello World

!!! Without quotes

Hello World

!!! Space entity

Hello World

!!! no-capitals

hello world
  1. View document

Package versions

  • Python: python --version
    Python 3.10.4
  • MkDocs: mkdocs --version
    mkdocs, version 1.3.0 from /home/gl513/.local/lib/python3.10/site-packages/mkdocs (Python 3.10)
  • Material: pip show mkdocs-material | grep -E ^Version
    Version: 8.2.15

Sidenote, in this section of the bug report template, python --version needs to be changed to python3 --version as it is more common now.

Configuration

site_name: My Docs
theme: material
markdown_extensions:
  - attr_list
  - admonition
  - pymdownx.details
  - pymdownx.superfences

System information

  • Operating system:

Operating System: Kubuntu 22.04
KDE Plasma Version: 5.24.4
KDE Frameworks Version: 5.92.0
Qt Version: 5.15.3
Kernel Version: 5.15.0-33-generic (64-bit)
Graphics Platform: X11
Processors: 8 × Intel® Core™ i7-8550U CPU @ 1.80GHz
Memory: 7.7 GiB of RAM
Graphics Processor: Mesa Intel® UHD Graphics 620

  • Browser:
Google Chrome 101.0.4951.64 (Official Build) (64-bit)
Revision d1daa9897e1bc1d507d6be8f2346e377e5505905-refs/branch-heads/4951@{#1208}
OS Linux
JavaScript V8 10.1.124.12
User Agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36
Command Line /usr/bin/google-chrome-stable --enable-crashpad --flag-switches-begin --flag-switches-end
Executable Path /opt/google/chrome/google-chrome
Profile Path /home/gl513/.config/google-chrome/Profile 1
commented

Thanks for reporting. Your use of admonitions is incorrect. The first token that occurs after !!! must be a qualifier, which is capitalized by Python Markdown. The documentation explains how to use admonitions:

!!! note "This title is correctly capitalized"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Closing.