Hello,
The documentation set I'm working on consists of a Flare project and a Hugo project. The outputs are located in separate folders, and there's a standalone html landing page outside of the projects. So my folder structure looks like this:
- index.html: the page that points to the various documentation sections like User Guide, Dev Guide, Reference Guide.
- flare documentation folder: this contains the Flare output (User Guide)
- hugo documentation folder: this contains the Hugo output (Reference Guide)
The Flare project uses the side navigation skin. I'd like the top entry in the side TOC to be a link to the top level index.html page and I'd like it to be a relative link. We have various relative links within the Flare docs pointing to pages in the Hugo docs, but when I try to assign a relative link to the TOC entry, it doesn't seem to work. Is this doable?
Thank you!
Relative link to external file in side TOC
-
bubble_ferret
- Jr. Propeller Head
- Posts: 5
- Joined: Wed Oct 14, 2020 4:43 am
Re: Relative link to external file in side TOC
Hi,
actually this should be doable. We already use relative links to external files in some of our TOC files. However, I am currently running into the same problem when I added new relative links in the TOC for a new target file.
We have multiple Flare projects with HTML5 output and in addition some other documentation. We also use side navigation skin and link to other manuals or html files from the TOC. Most of our manuals are translated and provided as multi-lingual version with a "Change language" button. Our final documentation is placed in a "help" folder:
As stated above, we already use some relative links in TOC to other external files that do work, mainly they navigate to the release notes, the doxygen reference or to the index.html of the other manual:
1. Often, the link from "manual_2" to the external files resolves in a way that it points to "help/manual_2/manual_1/en-us/index.html" or "help/manual_2/doxygen_reference/index.html". Thus it seems as if I just have to edit the link in the TOC file to move one folder level higher. However, this results in the same link target in the output. There is not difference. Why is the link to the external files resolved correclty in the output of "manual_1" and the English-only version of "manual_2" but not in the TOC for the multi-lingual "manual_2"? I really checked all kind of folder levels in the relative path within the TOC file.
2. When I check the respective .js file for the TOCs (e.g., toc_Chunkj0.js) that is generated during the Flare build, I can see that Flare changes the relative path that was defined in the TOC file and adds two "/../../" folder levels to the path. I know this behaviour from the past but sometimes it seems as if only one folder level is added or none at all. I'm not sure about the specific system behind this changes.
3. Regarding the TOC .js files: Several months/a year ago when we still used an older Flare version, we used the TOC .js files to check which path would be correct. At the time Flare had issues with resolving the relative paths to external links correctly, so we had to patch the relative links after the Flare build with a separate scritp during our overall documentation build. To find out which relative path is the correct one (and avoiding building the project after each change), we edited the path in the genereted toc_Chunk0.js file, refreshed the html file of the manual in the browser and then checked if the links is correct. Then we set the correct link when patching paths during our docu build. With a new Flare update some month ago, this patch was not necessary anymore and we could define the link directly in the TOC files. However, I remembered that we could test the relative link via the .js file. So I tried to do this now, but it seems as if this doesn't work anymore. Editing the path in the toc_Chunk0.js file makes no change in the link within the html file in the browser. So I wonder, if patching the paths via a separate script after the build (as during older Flare versions) will also not work anymore? I have to test this yet. Where there any internal changes in Flare how relative links are resolved in the TOC file?
4. The link from "manual_1" to "manual_2" navigates 5 level up (as defined in the TOC file). The link from the English-only "manual_2" to the "manual_1" also navigates 5 levels up. The folder structure of the output of the manuals differ because in "help/manual_1/" there are the language subfolders and within these folders the output files including the generated toc_Chunk0.js file. However, in the English-only "manual_2" there are no subfolders, the output files are directly placed in "help/manual_2". So why do I have to navigate 5 folder levels higher in both directions?
@bubble_ferret: Maybe you observed the same effects?
What could also influence how the links in the TOC files are generated during the Flare build? Does anyone have any idea why the links work in some manuals and in other not?
By the way, we are currently using Flare 2020 (but not the r2 because for this we have to make some further adjustments first).
Sorry for the XXL post. I tried to give all kind of information I have. I hope somebody can help.
actually this should be doable. We already use relative links to external files in some of our TOC files. However, I am currently running into the same problem when I added new relative links in the TOC for a new target file.
We have multiple Flare projects with HTML5 output and in addition some other documentation. We also use side navigation skin and link to other manuals or html files from the TOC. Most of our manuals are translated and provided as multi-lingual version with a "Change language" button. Our final documentation is placed in a "help" folder:
- help/manual_1/<LANG>/
- help/manual_2/<LANG>/
- help/manual_2_en/
- help/doxygen_reference/
- help/release_notes/
As stated above, we already use some relative links in TOC to other external files that do work, mainly they navigate to the release notes, the doxygen reference or to the index.html of the other manual:
- In the TOC of "manual_1":
- relative link to "help/release_notes/": "../../../../../release_notes/release_notes.html" => works fine
- relative link to "help/manual_2/": "../../../../../manual_2/index.html" => works fine
- In the TOC for the English-only version of "manual_2":
- relative link to "help/manual_1/en-us/": "../../../../../manual_1/en-us/index.html" => works fine
- relative link to "help/doxygen_reference/": "../../../../../communicator_reference/html/index.html" => works fine
- In the TOC for the multi-lingual version of "manual_2":
- relative link to "help/manual_1/en-us/": "../../../../../../manual_1/en-us/index.html" ( this would be one level higher than from the TOC of the English-only version of "manual_2" ) => doesn't work.
- relative link to "help/manual_1/en-us/": "../../../../../manual_1/en_Us/index.html" ( this would be same level as the link vice versa from the TOC of "manual_1" ) => doesn't work.
- relative link to "help/doxygen_reference/": "../../../../../../../../communicator_reference/html/index.html" ( this would be one level higher than from the TOC of the English-only version of "manual_2" ) => doesn't work.
1. Often, the link from "manual_2" to the external files resolves in a way that it points to "help/manual_2/manual_1/en-us/index.html" or "help/manual_2/doxygen_reference/index.html". Thus it seems as if I just have to edit the link in the TOC file to move one folder level higher. However, this results in the same link target in the output. There is not difference. Why is the link to the external files resolved correclty in the output of "manual_1" and the English-only version of "manual_2" but not in the TOC for the multi-lingual "manual_2"? I really checked all kind of folder levels in the relative path within the TOC file.
2. When I check the respective .js file for the TOCs (e.g., toc_Chunkj0.js) that is generated during the Flare build, I can see that Flare changes the relative path that was defined in the TOC file and adds two "/../../" folder levels to the path. I know this behaviour from the past but sometimes it seems as if only one folder level is added or none at all. I'm not sure about the specific system behind this changes.
3. Regarding the TOC .js files: Several months/a year ago when we still used an older Flare version, we used the TOC .js files to check which path would be correct. At the time Flare had issues with resolving the relative paths to external links correctly, so we had to patch the relative links after the Flare build with a separate scritp during our overall documentation build. To find out which relative path is the correct one (and avoiding building the project after each change), we edited the path in the genereted toc_Chunk0.js file, refreshed the html file of the manual in the browser and then checked if the links is correct. Then we set the correct link when patching paths during our docu build. With a new Flare update some month ago, this patch was not necessary anymore and we could define the link directly in the TOC files. However, I remembered that we could test the relative link via the .js file. So I tried to do this now, but it seems as if this doesn't work anymore. Editing the path in the toc_Chunk0.js file makes no change in the link within the html file in the browser. So I wonder, if patching the paths via a separate script after the build (as during older Flare versions) will also not work anymore? I have to test this yet. Where there any internal changes in Flare how relative links are resolved in the TOC file?
4. The link from "manual_1" to "manual_2" navigates 5 level up (as defined in the TOC file). The link from the English-only "manual_2" to the "manual_1" also navigates 5 levels up. The folder structure of the output of the manuals differ because in "help/manual_1/" there are the language subfolders and within these folders the output files including the generated toc_Chunk0.js file. However, in the English-only "manual_2" there are no subfolders, the output files are directly placed in "help/manual_2". So why do I have to navigate 5 folder levels higher in both directions?
@bubble_ferret: Maybe you observed the same effects?
What could also influence how the links in the TOC files are generated during the Flare build? Does anyone have any idea why the links work in some manuals and in other not?
By the way, we are currently using Flare 2020 (but not the r2 because for this we have to make some further adjustments first).
Sorry for the XXL post. I tried to give all kind of information I have. I hope somebody can help.
-
bubble_ferret
- Jr. Propeller Head
- Posts: 5
- Joined: Wed Oct 14, 2020 4:43 am
Re: Relative link to external file in side TOC
Thanks for taking the time to reply! I noticed the thing with the TOC_Chunk0.js file. It does add two levels for me too and editing it doesn't seem to influence the link. I'm using Flare 2020 r2, I haven't tried this with previous versions
Re: Relative link to external file in side TOC
Some further observations I made:
The final links in the TOC/toc_Chunk0.js need to be relative to the folder in which the "Content" folder is placed in the output. For my output with "help/manual/Content/", this means that I have to get back 2 levels higher to navigate to a different manual, release notes, whatever, in the help directoy, e.g., "/../../release_notes/release_notes.html".
One of the external links that works fine so far looks like this in the toc_Chunk.js file: '/../../../../../../../release_notes/release_notes.html'
When I change the link (in the toc_Chunk0.js) to be be relative to the folder in which "Content" is ("/../../release_notes/release_notes.html"), then the link works also fine in the browser.
This is strange so I checked some further adjustements. No matter how many folder levels I add, the final link in the browser always points to the correct location. It seems as if all levels higher than the first two are ignored. However, when I set the path thus to move only one level higher ("/../release_notes/release_notes.html"), the the link doesn't point to the same location anymore but to one level lower as usually expected.
In my new target in which the link doesn't work, I would need to move 3 levels up because the manual is multi-lingual and the "Content" folder is placed in the language folder: "help/manual/en-us/Content". Thus, the final link in the toc_Chunk0.js needs to be "/../../../help/release_notes/release_notes.html". However, I can see the same behaviour that all levels above the first two seem to be ignored. The link always points to "/help/manual/release_notes/release_notes.html".
But I'm still confused because in an other project with the same output structure the links works. It works with a different path than I would now expect but it works
So I contacted the MadCap support because I don't what to test or try out anymore. I will let you know if I know more.
The final links in the TOC/toc_Chunk0.js need to be relative to the folder in which the "Content" folder is placed in the output. For my output with "help/manual/Content/", this means that I have to get back 2 levels higher to navigate to a different manual, release notes, whatever, in the help directoy, e.g., "/../../release_notes/release_notes.html".
One of the external links that works fine so far looks like this in the toc_Chunk.js file: '/../../../../../../../release_notes/release_notes.html'
When I change the link (in the toc_Chunk0.js) to be be relative to the folder in which "Content" is ("/../../release_notes/release_notes.html"), then the link works also fine in the browser.
This is strange so I checked some further adjustements. No matter how many folder levels I add, the final link in the browser always points to the correct location. It seems as if all levels higher than the first two are ignored. However, when I set the path thus to move only one level higher ("/../release_notes/release_notes.html"), the the link doesn't point to the same location anymore but to one level lower as usually expected.
In my new target in which the link doesn't work, I would need to move 3 levels up because the manual is multi-lingual and the "Content" folder is placed in the language folder: "help/manual/en-us/Content". Thus, the final link in the toc_Chunk0.js needs to be "/../../../help/release_notes/release_notes.html". However, I can see the same behaviour that all levels above the first two seem to be ignored. The link always points to "/help/manual/release_notes/release_notes.html".
But I'm still confused because in an other project with the same output structure the links works. It works with a different path than I would now expect but it works
So I contacted the MadCap support because I don't what to test or try out anymore. I will let you know if I know more.
-
bubble_ferret
- Jr. Propeller Head
- Posts: 5
- Joined: Wed Oct 14, 2020 4:43 am
Re: Relative link to external file in side TOC
Hm. That's interesting. For me it seems no matter how many levels I add or what I change in the TOC_Chunk0.js file, it tries to point me to the highest level of the same project and won't go outside it. Would be curious to know what support says!
Re: Relative link to external file in side TOC
Hi,
I can give an update.
My support case is still open but in the meantime I think I found out why the external TOC links did work in my old project but not in one of my new projects.
In my new (very small) project, I placed most of my topics directly within the Content folder. By chance I noticed that the external TOC link worked when I opened one specific topic that is stored in a subfolder of the Content folder. And in my old project in which the links always worked, all my topics are also placed within subfolders and no topic is directly in the Content folder. So, I moved my topic to new subfolders in "Content" and now all external TOC links work.
So, the summary seems to be:
You have to place all topics within a subfolder of the Content folder. Then the external TOC links work.
@bubble_ferret: Let me know if this might also be the reason why it doesn't work in your project.
I also reported this to the MadCap support and I am now waiting if they can give any information why the external links do not work if a topic is placed directly in the Content folder.
I can give an update.
My support case is still open but in the meantime I think I found out why the external TOC links did work in my old project but not in one of my new projects.
In my new (very small) project, I placed most of my topics directly within the Content folder. By chance I noticed that the external TOC link worked when I opened one specific topic that is stored in a subfolder of the Content folder. And in my old project in which the links always worked, all my topics are also placed within subfolders and no topic is directly in the Content folder. So, I moved my topic to new subfolders in "Content" and now all external TOC links work.
So, the summary seems to be:
You have to place all topics within a subfolder of the Content folder. Then the external TOC links work.
@bubble_ferret: Let me know if this might also be the reason why it doesn't work in your project.
I also reported this to the MadCap support and I am now waiting if they can give any information why the external links do not work if a topic is placed directly in the Content folder.
-
bubble_ferret
- Jr. Propeller Head
- Posts: 5
- Joined: Wed Oct 14, 2020 4:43 am
Re: Relative link to external file in side TOC
Hi,
Thanks for the update! That might be my problem, yes. Unfortunately, I can't put that specific page into another subfolder within Content, because it's the overall landing page for all the docs. Sounds like this approach won't work and I'll have to look for another solution. Thanks for your help!
Thanks for the update! That might be my problem, yes. Unfortunately, I can't put that specific page into another subfolder within Content, because it's the overall landing page for all the docs. Sounds like this approach won't work and I'll have to look for another solution. Thanks for your help!