# 8.0 Migration Notes {: #\8.0}

## Overview

In general, there are a couple things to be aware of when upgrading to 8.0.

-   Some previously deprecated features are now removed: tabbed code blocks via SuperFences and ExtraRawHTML. These were
    originally deprecated as they are now redundant, and information is provided to allow you to get the same behavior
    as before.

-   One of the most invasive changes was adding the support of defining arbitrary attributes on code blocks in
    SuperFences via the brace header format. This caused numerous changes that affects those who define their own custom
    fences. If you are only using the builtin fences provided by SuperFences, you will likely notice no adverse affects,
    but will be able to take advantage of new the new features being offered.

## Better Support for JS Highlighters

-   SuperFences adds the ability, when using the brace header format (` ```{.lang .class #id attr=value} `) to add
    arbitrary HTML attributes to code blocks. By default, all classes, IDs and attributes are added to the `code` block
    of the generated output. The one exception is that the default `highlight` class is always added to the top level
    element.

    For instance, if a user needed to specify that a line number starts with an attribute `data-linenum-start`, they
    could simply use the brace header format to define this new attribute:

    ````
    ```{.python data-linenum-start="30"}
    import sys
    ```
    ````

    Attributes will only be used when Python Markdown's [`attr_list`][attr-list] extension is enabled. Attributes will
    also be ignored when using Pygments as Pygments doesn't directly support adding IDs or arbitrary attributes.

    This allows for more extensive configuration when using JavaScript highlighters. Now users can set the appropriate
    attributes to configure line numbers and other highlighter specific features without the Highlight extension getting
    in the way.

-   Some JS highlighters may require attributes and classes to be assigned to the `pre` element, so the
    [Highlight](../../extensions/highlight.md) extension has added a new feature called `code_attr_on_pre`. This new
    option will ensure that custom classes, IDs, and attributes are applied to the `pre` element instead.

-   By default, JavaScript ready code blocks would normally have the specified language class prefixed with `language-`.
    This follows the HTML 5 specification, but some highlighters may prefer something different. The prefix can now be
    changed with the new [Highlight](../../extensions/highlight.md) option called `language_prefix`.

## Retired Features

-   The legacy tab feature has been removed from SuperFences. This does not mean tab support is dead as the
    [Tabbed](../../extensions/tabbed.md) extension actually provides an even more useful, general purpose, solution. It
    was impossible to keep this legacy feature around, in its current implementation, after the restructure of for
    attribute list support, so we decided to officially retire this already deprecated feature.

-   ExtraRawHTML has officially been removed. This extension only existed because Python Markdown did not have the
    feature exposed in a manner that allowed you to use it without including all of their "Extra" extension, now that
    Python  Markdown has exposed this extension by itself, there is no longer a reason for us expose it via
    ExtraRawHTML. Please use Python Markdown's [`md_in_html`][md-in-html] extension instead to get the same exact
    functionality.

## Custom Fence Changes

SuperFences made numerous changes so that users who wish not to use Pygments can set arbitrary attributes via the brace
header format so that can more extensively configure their code blocks for JavaScript syntax highlighters. This required
changes to how custom fences were handled.

-   Custom fence formatters are now expected to take a new keyword attribute called `attrs`. `attrs` contains a
    dictionary of key/value pairs defining attributes that should be attached to the main block element generated by a
    given formatter. In general, custom formatters *should* handle these, but are not required to.  At the very least,
    they should be updated to take the argument even if they don't do anything with them. Custom fences that do not
    accept this parameter will silently fail. If your custom fence already accepts `**kwargs` (as recommended in the 7.0
    release), your fence should continue to work even you do not do anything with the attributes. No use and apply the
    new, attributes, you will have to read the `attrs` parameter and set those to one of the elements in your generated
    HTML.

-   Custom fence validators have been updated to handle validation of inputs by assigning valid inputs to either an
    `options` dictionary or an `attrs` dictionary. The new function signature looks like this:
    `#!py3 validator(language, inputs, options, attrs, md):`.

    -   `inputs` contains all the parsed key/value pairs and should **never** be modified. `options` should have inputs
        added to it that configure a formatter's features. You should parse, format and assign all inputs that are
        considered options to the `option` dictionary.

    -   `attrs` normally would contain copies of any non-option key/value pairs from inputs, unaltered. These would
        usually be applied to HTML elements as attributes.

    -   `md` is the `Markdown` class instance and is useful if you want to access meta data or anything else in your
        validator.

        SuperFences will detect if you are using an older validator and should gracefully transition and use the old
        format, but it is strongly recommended to use the new format. If you run into any issues, you are required to
        update to the new format. In a future version, the graceful transition will be removed.

-   Since attributes and options are now parsed via the [`attr_list`][attr-list] extension, custom fences can no longer
    allow inputs in the form `key=` (with no value), they must be in the form `key`, `key="value"` or `key=value`. When
    defining an input in the form `key` (with no value), the value will be the `key` name (this is how
    [`attr_list`][attr-list] handles such cases). To specify an empty `key`, please use `key=""`.

-   If a custom validator fails, SuperFences will now gracefully handle the error and try the next custom fence in the
    queue. If a custom formatter fails. If you suspect your custom validator is not working, you should add your own
    debug code to your custom fence to verify whether it is failing or not.

-   SuperFences will gracefully handle the error and abort processing the fence. If you suspect your custom formatter is
    not working, you should add your own debug code to your custom fence to verify whether it is failing or not.

## New Extension

[SaneHeaders](../../extensions/saneheaders.md) implements Markdown headers more like CommonMark. Headers require a space
after the `#` symbol in order for the line to be treated as a header. This allows you to use
[MagicLink](../../extensions/magiclink.md) issues at the start of a line. See
[SaneHeaders documentation](../../extensions/saneheaders.md) for more information.
