Problem/Motivation

PHP code blocks in the mkdocs documentation have no syntax coloring. Two issues cause this:

  1. The Pygments PHP lexer expects code to start with <?php. Without it, everything is treated as plain text — no highlighting tokens are generated.
  2. The Material theme applies its own colors via CSS custom properties (--md-code-hl-variable-color, etc.) that default most tokens to gray. The original pygments.css used bare selectors (.nv, .na, etc.) which lose the specificity battle against Material's scoped selectors.

Steps to reproduce

  1. Build the mkdocs site: mkdocs build
  2. Open any page with a PHP code block (e.g. Domain > Path prefix)
  3. All PHP code appears in a single gray color — no distinction between keywords, variables, strings, comments, etc.

Proposed resolution

mkdocs.yml: Configure pymdownx.highlight with extend_pygments_lang to pass startinline: true to the PHP lexer, so PHP code blocks are highlighted without needing <?php. Also enable pygments_lang_class to add language classes to the wrapper div.

pygments.css: Rewrite with CSS nesting under .highlight to increase specificity and override Material theme defaults. Lighten comment color from #3d7b7b to #4f7676 for WCAG AA contrast compliance.

Remaining tasks

Review and commit.

Issue fork domain-3578659

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

mably created an issue. See original summary.

mably’s picture

Issue summary: View changes

  • mably committed 5a53d7f7 on 3.x
    task: #3578659 PHP code blocks in the mkdocs documentation have no...
mably’s picture

Status: Active » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.