How to create MSDN like links in Sandcastle documentation website?

Question

I've generated a website documentation of my project with Sandcastle. This website uses frames so when I click though sites my URL in browser does not change.

I would like to have URL changed in browser when I browse through website documentation generated with Sandcastle. Why? Because I would like to link to concrete subpages of documentation from other parts of my developer environment.

And further more I would like to have this links permanent. So when I generate once again documentation from new version of my project, links will not change so that I will not need to change all links to new.

Is this possible and how to acomplish this?

Answer 1

Hello!

In order to create correct links to specific subpages of documentation you may use similar request: $DOCUMENTATION_ROOT$/Index.aspx?topic=html/$TOPIC_ID$.htm

E.g. http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/8dcbb69b-7a1a-4049-8e6b-2bf344efbbc9.htm instead of http://www.ewoodruff.us/shfbdocs/html/8dcbb69b-7a1a-4049-8e6b-2bf344efbbc9.htm

Answer 2

If you add the code below to the top of SplitScreen.js the browser will "inject" the TOC frame and focus on the content you linked directly to (using the trick Vitaly Shibaev showed).

if (window==top) {
    window.location = "/?topic=" + (window.location.pathname.substring(1));
}

This code works it the documentation is placed at the root of your website - if you have it in a sub-folder you need to expand on "/?topic" and remove the sub-folder part from the pathname part.

With this change you can use the "direct links". I also expect people who find you via Google get a better experience (getting the content they searched for AND the TOC bar).

Answer 3

Vitaliy and mawtex have solved the 'how to link to documentation subpages' part of your question.

The "making links permanent so they do not change when regenerating documentation" part of your questions is solved automatically, since the html file names created are based on a hash of the topic name by default. I.e. If you do not change the part of your code that you are documenting, then it will use the same file name.

You can change the way that html file names are generated, but all given methods are based on the member name or a hash of the topic ID, so links shouldn't break if the code hasn't changed.

See Sandcastle Help File Builder's NamingMethod documentation for more info.