Define How You Want Acrolinx To Track Your Content

By default, Acrolinx uses the file path as the unique reference for your content. Basically, what you see as the "Source" in a Scorecard is the default reference. 

If you're happy with this, then you don't need to change anything. But maybe you have a better way of tracking your content. 

Why would you need a better way? Well, consider the following scenario.

The Problem

You're working on a Markdown file called "introduction-to-demo-inc-greeblies.md". For arguments sake, let's say that you moved it to different locations and even changed your mind about the file name just before you published it.

The evolution of your checking statistics would look something like this:

Check TimeFile PathContent ReferenceScoreImprovement
First version/doc/drafts/introduction-to-demo-inc-greeblies.md"/doc/drafts/introduction-to-demo-inc-greeblies.md"65No Previous Data
Revised version/doc/demo-inc/topics/introduction-to-demo-inc-greeblies.md"/doc/demo-inc/topics/introduction-to-demo-inc-greeblies.md"78No Previous Data
Final version/doc/demo-inc/topics/overview-of-demo-inc-greeblies.md"/doc/acme/topics/overview-of-demo-inc-greeblies.md"84No Previous Data

 The last column shows "No Previous Data" because Acrolinx treats each version as a separate file rather than different iterations of the same file.

The Solution

To get around this problem, you can tell Acrolinx to use a different reference. As long as you have an attribute that is stable across content versions, you'll be able to track that content.

For example, the front matter in your Markdown file might contain a "slug" parameter. You've set the slug to "greeblies-intro" and it doesn't change between the different versions. You can configure Acrolinx to use the value for the "slug" parameter as the content reference. 

The evolution of your checking statistics would now look something like this:

Check TimeFile PathContent ReferenceScoreImprovement
First version/doc/drafts/introduction-to-demo-inc-greeblies.md"greeblies-intro"65No Previous Data
Revised version/doc/acme-widgets/topics/introduction-to-demo-inc-greeblies.md"greeblies-intro"78+13
Final version/doc/acme-widgets/topics/overview-of-demo-inc-greeblies.md"greeblies-intro"84+6

The "Improvement" column shows progress because all quality scores are attributed to a single content reference "greeblies-intro".


To Configure the Content Reference, Follow These Steps:

  1. In the Dashboard, navigate to Guidance Settings > Content Profiles, and click on the relevant Content Profile. For our Markdown example above, we'd pick the Markdown Content Profile.
  2. Navigate to DOCUMENT INFORMATION > Document Identification.
  3. Select Extract document identifier from document and enter the XPath for your stable attribute.
    For example, to use the "slug" parameter in Markdown front matter, your XPath could look like this:

You can test whether your content reference is working by checking a relevant file, then going to the Scorecard Archive dashboard. In the Document column, instead of the file path you should now see the content reference that you defined.