How are heading IDs generated?

Programmater · September 9, 2025, 2:18pm

Hello,

I am trying to find the logic on how IDs are generated from IDs.

For example having the following heading is converted to #HExampleHeading

= Example Heading =

My goal is to go from URL back to headings in the raw source of the page rather than the rendered page.

I have been able to reproduce the logic for most simple situations but there are still edge cases for which my logic fails, therefore I wanted to look at reproducing directly the logic used for rendering the headings.

Thanks!

CharpentierLucas · September 9, 2025, 3:15pm

Hi!

For anything related to how we render syntax in XWiki, you can look into the project xwiki-rendering.

For your specific question, here are a couple links to places from where you should be able to find what you’re looking for

Why there’s a H before any title ID: xwiki-rendering/xwiki-rendering-syntaxes/xwiki-rendering-syntax-wikimodel/src/main/java/org/xwiki/rendering/internal/parser/wikimodel/DefaultXWikiGeneratorListener.java at 23d8fe8ffc72635c36b13551e6d0f0d27b8d5fc8 · xwiki/xwiki-rendering · GitHub
How is the ID built: xwiki-rendering/xwiki-rendering-api/src/main/java/org/xwiki/rendering/util/IdGenerator.java at aae47a0759cf66888f92d04bbefbbdbd236c1ae8 · xwiki/xwiki-rendering · GitHub (you probably also want to check out the function normalizeId)

Hope this helps!

Lucas C.

Programmater · September 9, 2025, 3:43pm

Great, thank you! I did some digging myself in the rendering Github project but couldn’t find the exact place where the logic was done!

I’ll get started working on that and will report back if we have any further issues with it.

Thanks a lot for you help!

hengels · September 10, 2025, 6:11am

{{groovy}}
import org.xwiki.rendering.util.IdGenerator;
def id = new IdGenerator().generateUniqueId("H", "Example Heading");
{{/groovy}}

CharpentierLucas · September 10, 2025, 8:21am

I looked a bit more into it:

Remove all spaces
Convert all non allowed characters (xwiki-rendering/xwiki-rendering-api/src/main/java/org/xwiki/rendering/util/IdGenerator.java at aae47a0759cf66888f92d04bbefbbdbd236c1ae8 · xwiki/xwiki-rendering · GitHub ) From what I understand the conversion function is toHex (quite uncertain, I didn’t figure out all the code in here).

Allowed characters are 1->9, a->z , A->Z , “:” “_” “.” and “-”.

github.com/xwiki/xwiki-rendering

xwiki-rendering-api/src/main/java/org/xwiki/rendering/util/IdGenerator.java

aae47a075


      
          private static final BitSet ALLOWED = new BitSet(256);
          
          static {
              // digits
              for (int i = '0'; i <= '9'; i++) {
                  ALLOWED.set(i);
              }
          
              // alpha
              for (int i = 'a'; i <= 'z'; i++) {
                  ALLOWED.set(i);
              }
              for (int i = 'A'; i <= 'Z'; i++) {
                  ALLOWED.set(i);
              }
          
              ALLOWED.set(':');
              ALLOWED.set('_');
              ALLOWED.set('.');
              ALLOWED.set('-');
          }