diff options
| author | Dan Allen <dan.j.allen@gmail.com> | 2021-09-24 23:53:56 -0600 |
|---|---|---|
| committer | Dan Allen <dan.j.allen@gmail.com> | 2021-09-25 02:54:07 -0600 |
| commit | 6df9eb51ec718602c5ab0cf415ddd151722a54d6 (patch) | |
| tree | 3a41489e4376b131154070f102332cdfd94eff7b /docs | |
| parent | 6efc2e9b247eec8f832e2fbf05e5499386407b62 (diff) | |
add note to AsciiDoc.py migration guide about differences in ID generation
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/modules/migrate/pages/asciidoc-py.adoc | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/docs/modules/migrate/pages/asciidoc-py.adoc b/docs/modules/migrate/pages/asciidoc-py.adoc index a898039f..884859fa 100644 --- a/docs/modules/migrate/pages/asciidoc-py.adoc +++ b/docs/modules/migrate/pages/asciidoc-py.adoc @@ -168,6 +168,16 @@ To revert this behavior, explicitly unset `compat-mode`. |See xref:asciidoc:sections:numbers.adoc[]. |=== +Asciidoctor is more careful when deriving automatic IDs for sections from the section title to avoid generating obscure IDs. + +* Asciidoctor removes any start and end HTML/XML tags, whereas AsciiDoc.py does not. +* Asciidoctor removes any character references (e.g., `\©`), whereas AsciiDoc.py does not (see next rule). +* Asciidoctor removes any invalid characters (e.g., `$`), whereas AsciiDoc.py replaces these characters with the value of the `idseparator` attribute. +* Asciidoctor automatically generates IDs for discrete headings, whereas AsciiDoc.py does not. + +To ensure your IDs have maximum portability, it's best to define them explicitly if the section title contains special characters or formatting. + + === Tables [cols="~,~,~,~"] |