Function
docutils.nodes.make_id

Signature

make_id(string)

Documentation String

Convert string into an identifier and return it.

Docutils identifiers will conform to the regular expression [a-z](-?[a-z0-9]+)*. For CSS compatibility, identifiers (the "class" and "id" attributes) should have no underscores, colons, or periods. Hyphens may be used.

  • The HTML 4.01 spec defines identifiers based on SGML tokens:

    ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

  • However the CSS1 spec defines identifiers based on the "name" token, a tighter interpretation ("flex" tokenizer notation; "latin1" and "escape" 8-bit characters have been replaced with entities):

    unicode     \[0-9a-f]{1,4}
    latin1      [¡-ÿ]
    escape      {unicode}|\[ -~¡-ÿ]
    nmchar      [-a-z0-9]|{latin1}|{escape}
    name        {nmchar}+
    

The CSS1 "nmchar" rule does not include underscores ("_"), colons (":"), or periods ("."), therefore "class" and "id" attributes should not contain these characters. They should be replaced with hyphens ("-"). Combined with HTML's requirements (the first character must be a letter; no "unicode", "latin1", or "escape" characters), this results in the [a-z](-?[a-z0-9]+)* pattern.