docToolchain
Question to asciidoc2Confluence - How to correctly cross reference pages.
At first, thank you very much for this great project 👏
I'm already successfully using the publishToConfluence task. The only thing I can't get to work is, that links between pages are working. I've tried several AsciiDoc link mechanisms (e.g. xref, link), but none of them works. That means, that the link always points to the same document.
This is an extract of my current documentation:
Content.adoc
= Edge documentation
:toc:
:doctype: book
:toclevels: 9
:icons: font
:leveloffset: +1
include::ContentDeveloperFAQ.adoc[]
:leveloffset: -1
ContentDeveloperFAQ.adoc
= Developer FAQ
:leveloffset: +1
include::Ht-create-a-new-manifest.adoc[]
include::Ht-deploy-a-new-version-of-my-module.adoc[]
:leveloffset: -1
Ht-deploy-a-new-version-of-my-module.adoc None of the links are working, specified in Prerequisites.
= How to deploy a new version of my module
:toc:
:icons: font
:example-number: 0
:table-number: 0
== Prerequisites
* The manifest file is already available in the repository. *If not, check xref:Ht-create-a-new-manifest#_how_to_create_a_new_manifest[How to create a new manifest] out.*
* The manifest file is already available in the repository. *If not, check <<Ht-create-a-new-manifest#_how_to_create_a_new_manifest, How to create a new manifest>> out.*
* The manifest file is already available in the repository. *If not, check link:Ht-create-a-new-manifest.adoc#_how_to_create_a_new_manifest[How to create a new manifest] out.*
Ht-create-a-new-manifest.adoc
= How to create a new manifest
:toc:
:icons: font
:example-number: 0
:table-number: 0
== Prerequisites
What is the correct way to cross reference pages? Thanks in advance.
Hi, If you are using the cloud version, I fear it isn't possible anymore. My workaround is to upload all pages without links first. Then add the absolute links from the url bar and upload again. However, Achors still work, added after '#'
For legacy mode (on-prem) someone else may help?
ok, this is a tricky one.
Let's first discuss how publishToConfluence works. First, generateHTML creates a basic HTML file. A single-page-view. This file is then parsed and split up by headlines, depending on your configuration.
Links within the document should all start with a #, because they only link to an anchor on the page itself. But now we have multiple pages. So there is a script which tries to re-write those links: https://github.com/docToolchain/docToolchain/blob/ng/scripts/asciidoc2confluence.groovy#L422
Links to another document are a different thing.
now back to your problem description: can you please check what kind of links are generated for your three examples when you use generateHTML? At least one of them should only produce an href="#..." - at least if your link just point to another reference on the same page.
Next step will be to analyze why this is not converted the right way.
Hi @rdmueller ,
many thanks for your quick reply and the steps to analyze the problem.
I ran the command you described and I got the following HTML output. On the right handside you can see the corresponding asciidoc format.
Also, I would like to provide you my configuration file so that you can properly drill down into the problem 😀
outputPath = 'build'
// Path where the docToolchain will search for the input files.
// This path is appended to the docDir property specified in gradle.properties
// or in the command line, and therefore must be relative to it.
inputPath = 'docs';
pdfThemeDir = './src/docs/pdfTheme'
inputFiles = [
[file: 'Content.adoc', formats: ['html', 'pdf']]
/** inputFiles **/
]
//folders in which asciidoc will find images.
//these will be copied as resources to ./images
//folders are relative to inputPath
imageDirs = [
'./images/'
]
// these are directories (dirs) and files which Gradle monitors for a change
// in order to decide if the docs have to be re-build
taskInputsDirs = [
"${inputPath}",
"${inputPath}/images",
]
taskInputsFiles = []
//*****************************************************************************************
confluence = [:]
confluence.with {
input = [
[file: "build/html5/Content.html", ancestorId: "2124226917"],
]
// You can pass a Confluence Personal Access Token as the bearerToken. It is an alternative to credentials. Do not confuse it with apiKey.
bearerToken = "${System.getenv("CONFLUENCE_PAT")}"
// endpoint of the confluenceAPI (REST) to be used
// verfiy that you got the correct endpoint by browsing to
// https://[yourServer]/[context]/rest/api/user/current
// you should get a valid json which describes your current user
// a working example is https://arc42-template.atlassian.net/wiki/rest/api/user/current
api = 'https://my-confluence-rest-api/'
// Additionally, spaceKey, subpagesForSections, pagePrefix and pageSuffix can be globally defined here. The assignment in the input array has precedence
// the key of the confluence space to write to
spaceKey = 'BSP'
// variable to determine how many layers of sub pages should be created
subpagesForSections = 2
// the pagePrefix will be a prefix for each page title
// use this if you only have access to one confluence space but need to store several
// pages with the same title - a different pagePrefix will make them unique
pagePrefix = '[Edge] '
// HTML Content that will be included with every page published
// directly after the TOC. If left empty no additional content will be added
extraPageContent = '<ac:structured-macro ac:name="warning"><ac:parameter ac:name="title" /><ac:rich-text-body>This is a auto-generated page, do not edit!</ac:rich-text-body></ac:structured-macro>'
// enable or disable attachment uploads for local file references
enableAttachments = false
}
Thank you very much for your effort and patience.