Add lang_prefix config option.

Author: waylan

.spell-dict

@@ -77,6 +77,8 @@ PHP
 Posix
 postprocessor
 postprocessors
+prepend
+prepended
 preprocessor
 preprocessors
 Pygments

docs/change_log/release-3.3.md

@@ -7,7 +7,29 @@ PyPy3.
 
 ## Backwards-incompatible changes
 
-...
+### The prefix `language-` is now prepended to all language classes by default on code blocks.
+
+The [HTML5 spec][spec] recommends that the class defining the language of a code block be prefixed with `language-`.
+Therefore, by default, both the [fenced_code] and [codehilite] extensions now prepend the prefix when code
+highlighting is disabled.
+
+If you have previously been including the prefix manually in your fenced code blocks, then you will not want a second
+instance of the prefix. Similarly, if you are using a third party syntax highlighting tool which does not recognize
+the prefix, or requires a different prefix, then you will want to redefine the prefix globally using the `lang_prefix`
+configuration option of either the `fenced_code` or `codehilite` extensions.
+
+For example, to configure `fenced_code` to not apply any prefix (the previous behavior), set the option to an empty string:
+
+```python
+from markdown.extensions.fenced_code import FencedCodeExtension
+
+markdown.markdown(src, extensions=[FencedCodeExtension(lang_prefix='')])
+```
+
+!!! note
+ When code highlighting is [enabled], the output from Pygments is used unaltered. Currently, Pygments does not
+ provide an option to include the language class in the output, let alone prefix it. Therefore, any language prefix
+ is only applied when syntax highlighting is disabled.
 
 ## New features
 
@@ -33,3 +55,8 @@ The following bug fixes are included in the 3.3 release:
 
 * Fix issues with complex emphasis (#979).
 * Limitations of `attr_list` extension are Documented (#965).
+
+[spec]: https://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
+[fenced_code]: ../extensions/fenced_code_blocks.md
+[codehilite]: ../extensions/code_hilite.md
+[enabled]: ../extensions/fenced_code_blocks.md#enabling-syntax-highlighting

docs/extensions/code_hilite.md

@@ -185,7 +185,7 @@ configuring extensions.
 
 The following options are provided to configure the output:
 
-* **`linenums`**:
+* **`linenums`**{ #linenums }:
  An alias to Pygments' `linenos` formatter option. Possible values are `True` for yes, `False` for no and `None`
  for auto. Defaults to `None`.
 
@@ -195,39 +195,44 @@ The following options are provided to configure the output:
  Using `False` will turn off all line numbers, even when using shebangs
  (`#!`) for language identification.
 
-* **`guess_lang`**:
+* **`guess_lang`**{ #guess_lang }:
  Automatic language detection. Defaults to `True`.
 
  Using `False` will prevent Pygments from guessing the language, and thus
  highlighting blocks only when you explicitly set the language.
 
-* **`css_class`**:
+* **`css_class`**{ #css_class }:
  An alias to Pygments `cssclass` formatter option. Set CSS class name for the wrapper `<div>` tag. Defaults to
  `codehilite`.
 
-* **`pygments_style`**:
+* **`pygments_style`**{ #pygments_style }:
  Pygments HTML Formatter Style (`ColorScheme`). Defaults to `default`.
 
  !!! Note
  This is useful only when `noclasses` is set to `True`, otherwise the
  CSS styles must be provided by the end user.
 
-* **`noclasses`**:
+* **`noclasses`**{ #noclasses }:
  Use inline styles instead of CSS classes. Defaults to `False`.
 
-* **`use_pygments`**:
+* **`use_pygments`**{ #use_pygments }:
  Specifies the use of Pygments in generating the output.
 
  If `True` (the default) and Pygments is available, CodeHilite will use
  Pygments to analyze and format the output. Additionally, if using Pygments
  &gt;= 2.4, the output will be wrapped in `<code>` tags, whereas earlier
  versions will not.
 
- Otherwise, Pygments will not be used. If a language is defined for a code
- block, it will be assigned to the `<code>` tag as a class in the manner
- suggested by the [HTML5 spec][spec] (alternate output will not be
- entertained) and may be used by a JavaScript library in the browser to
- highlight the code block.
+ Otherwise, Pygments will not be used. If a language is defined for a code block, it will be assigned to the
+ `<code>` tag as a class in the manner suggested by the [HTML5 spec][spec] and may be used by a JavaScript library
+ in the browser to highlight the code block. See the [`lang_prefix`](#lang_prefix) option to customize the prefix.
+
+* **`lang_prefix`**{ #lang_prefix }:
+ The prefix prepended to the language class assigned to the HTML `<code>` tag. Default: `language-`.
+
+ This option only applies when `use_pygments` is `False` as Pygments does not provide an option to include a
+ language prefix.
+
 
 * Any other Pygments' options:
 

docs/extensions/fenced_code_blocks.md

@@ -116,7 +116,8 @@ Either of the above examples will output the following HTML:
 
 Note that the language name has been prefixed with `language-` and it has been assigned to the `class` attribute on
 the `<code>` tag, which is the format suggested by the [HTML 5 Specification][html5] (see the second "example" in the
-Specification).
+Specification). While `language` is the default prefix, the prefix may be overridden using the
+[`lang_prefix`](#lang_prefix) configuration option.
 
 #### Classes
 
@@ -240,7 +241,12 @@ they would if syntax highlighting was disabled for that code block regardless of
 
 See [Extensions] for general extension usage. Use `fenced_code` as the name of the extension.
 
-This extension does not accept any special configuration options.
+See the [Library Reference] for information about configuring extensions.
+
+The following option is provided to configure the output:
+
+* **`lang_prefix`**{#lang_prefix}:
+ The prefix prepended to the language class assigned to the HTML `<code>` tag. Default: `language-`.
 
 A trivial example:
 
@@ -260,3 +266,4 @@ markdown.markdown(some_text, extensions=['fenced_code'])
 [PHP lexer's]: https://pygments.org/docs/lexers/#lexers-for-php-and-related-languages
 [setup]: ./code_hilite.md#setup
 [Extensions]: ./index.md
+[Library Reference]: ../reference.md#extensions

markdown/extensions/codehilite.py

@@ -95,6 +95,7 @@ def __init__(self, src, **options):
  self.lang = options.pop('lang', None)
  self.guess_lang = options.pop('guess_lang', True)
  self.use_pygments = options.pop('use_pygments', True)
+ self.lang_prefix = options.pop('lang_prefix', 'language-')
 
  if 'linenos' not in options:
  options['linenos'] = options.pop('linenums', None)
@@ -145,7 +146,7 @@ def hilite(self):
  txt = txt.replace('"', '"')
  classes = []
  if self.lang:
- classes.append('language-{}'.format(self.lang))
+ classes.append('{}{}'.format(self.lang_prefix, self.lang))
  if self.options['linenos']:
  classes.append('linenums')
  class_str = ''
@@ -268,7 +269,11 @@ def __init__(self, **kwargs):
  'use_pygments': [True,
  'Use Pygments to Highlight code blocks. '
  'Disable if using a JavaScript library. '
- 'Default: True']
+ 'Default: True'],
+ 'lang_prefix': [
+ 'language-',
+ 'Prefix prepended to the language when use_pygments is false. Default: "language-"'
+ ]
  }
 
  for key, value in kwargs.items():

markdown/extensions/fenced_code.py

@@ -26,12 +26,17 @@
 
 
 class FencedCodeExtension(Extension):
+ def __init__(self, **kwargs):
+ self.config = {
+ 'lang_prefix': ['language-', 'Prefix prepended to the language. Default: "language-"']
+ }
+ super().__init__(**kwargs)
 
  def extendMarkdown(self, md):
  """ Add FencedBlockPreprocessor to the Markdown instance. """
  md.registerExtension(self)
 
- md.preprocessors.register(FencedBlockPreprocessor(md), 'fenced_code_block', 25)
+ md.preprocessors.register(FencedBlockPreprocessor(md, self.getConfigs()), 'fenced_code_block', 25)
 
 
 class FencedBlockPreprocessor(Preprocessor):
@@ -48,9 +53,9 @@ class FencedBlockPreprocessor(Preprocessor):
  re.MULTILINE | re.DOTALL | re.VERBOSE
  )
 
- def __init__(self, md):
+ def __init__(self, md, config):
  super().__init__(md)
-
+ self.config = config
  self.checked_for_deps = False
  self.codehilite_conf = {}
  self.use_attr_list = False
@@ -116,7 +121,10 @@ def run(self, lines):
  else:
  id_attr = class_attr = kv_pairs = ''
  if classes:
- class_attr = ' class="{}"'.format('language-' + ' '.join(classes))
+ class_attr = ' class="{}{}"'.format(
+ self.config.get('lang_prefix', 'language-'),
+ ' '.join(classes)
+ )
  if id:
  id_attr = ' id="{}"'.format(id)
  if self.use_attr_list and config and not config.get('use_pygments', False):

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
  - Test Tools: test_tools.md
  - Contributing to Python-Markdown: contributing.md
  - Change Log: change_log/index.md
+ - Release Notes for v.3.3: change_log/release-3.3.md
  - Release Notes for v.3.2: change_log/release-3.2.md
  - Release Notes for v.3.1: change_log/release-3.1.md
  - Release Notes for v.3.0: change_log/release-3.0.md

tests/test_syntax/extensions/test_code_hilite.py

@@ -128,6 +128,24 @@ def test_codehilite_use_pygments_false(self):
  )
  self.assertOutputEquals('<?php print("Hello World"); ?>', expected, lang='php', use_pygments=False)
 
+ def test_codehilite_lang_prefix_empty(self):
+ expected = (
+ '<pre class="codehilite"><code class="php">&lt;?php print(&quot;Hello World&quot;); ?&gt;\n'
+ '</code></pre>'
+ )
+ self.assertOutputEquals(
+ '<?php print("Hello World"); ?>', expected, lang='php', use_pygments=False, lang_prefix=''
+ )
+
+ def test_codehilite_lang_prefix(self):
+ expected = (
+ '<pre class="codehilite"><code class="lang-php">&lt;?php print(&quot;Hello World&quot;); ?&gt;\n'
+ '</code></pre>'
+ )
+ self.assertOutputEquals(
+ '<?php print("Hello World"); ?>', expected, lang='php', use_pygments=False, lang_prefix='lang-'
+ )
+
  def test_codehilite_linenos_true(self):
  if has_pygments:
  expected = (
@@ -495,6 +513,32 @@ def testUsePygmentsFalse(self):
  extensions=[CodeHiliteExtension(use_pygments=False)]
  )
 
+ def testLangPrefixEmpty(self):
+ self.assertMarkdownRenders(
+ (
+ '\t:::Python\n'
+ '\t# A Code Comment'
+ ),
+ (
+ '<pre class="codehilite"><code class="python"># A Code Comment\n'
+ '</code></pre>'
+ ),
+ extensions=[CodeHiliteExtension(use_pygments=False, lang_prefix='')]
+ )
+
+ def testLangPrefix(self):
+ self.assertMarkdownRenders(
+ (
+ '\t:::Python\n'
+ '\t# A Code Comment'
+ ),
+ (
+ '<pre class="codehilite"><code class="lang-python"># A Code Comment\n'
+ '</code></pre>'
+ ),
+ extensions=[CodeHiliteExtension(use_pygments=False, lang_prefix='lang-')]
+ )
+
  def testDoubleEscape(self):
  if has_pygments:
  expected = (

tests/test_syntax/extensions/test_fenced_code.py

@@ -703,3 +703,39 @@ def testFencedLanguagePygmentsEnabledInAttrNoCodehiliteWithAttrList(self):
  ),
  extensions=['fenced_code', 'attr_list']
  )
+
+ def testFencedLanguageNoPrefix(self):
+ self.assertMarkdownRenders(
+ self.dedent(
+ '''
+ ``` python
+ # Some python code
+ ```
+ '''
+ ),
+ self.dedent(
+ '''
+ <pre><code class="python"># Some python code
+ </code></pre>
+ '''
+ ),
+ extensions=[markdown.extensions.fenced_code.FencedCodeExtension(lang_prefix='')]
+ )
+
+ def testFencedLanguageAltPrefix(self):
+ self.assertMarkdownRenders(
+ self.dedent(
+ '''
+ ``` python
+ # Some python code
+ ```
+ '''
+ ),
+ self.dedent(
+ '''
+ <pre><code class="lang-python"># Some python code
+ </code></pre>
+ '''
+ ),
+ extensions=[markdown.extensions.fenced_code.FencedCodeExtension(lang_prefix='lang-')]
+ )