[Openstack-docs] Conventions for filenames and chapter/section IDs

David Cramer david.cramer at RACKSPACE.COM
Mon May 26 15:43:52 UTC 2014


On 5/26/14, 10:07 AM, Nick Chase wrote:
> Plus my concern in changing Id values is breaking any references.

You can reduce (but not eliminate) the impact of a file name change by
changing the file names via a processing instruction:

<section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>...

If you use <?dbhtml filename="..."?> you'll get the aesthetically
pleasing intro.html file name without having to change the xml:id and
break xrefs to the section. However, if you have external links to
some-dumb-id.html from other documents, those links would obviously break.

Regardless of the publishing tool chain, when changing the names of
existing resources on the web, the best approach is to add 301 redirects
to avoid breaking bookmarks, links, and losing SEO karma.

Regards,
David




More information about the Openstack-docs mailing list