AsciiDoc include macro isn't working

[iansk]

AsciiDoc has a macro that lets you pull in adoc content from other files. The include:: macro isn't working on our Franklin pages. See the official documentation for include:: here.

This page shows the issue (scroll to the bottom of the page):

Link: Onboard Accounts for Agentless Scanning

Relevant underlying doc source:

include::frag_start-agentless-scan.adoc[leveloffset=1]

Screenshot:

[iansk]

Re-opening this issue. I've found other instances where the include:: macro still isn't being processed properly.

See the following links. This isn't a comprehensive list, it's just what I spot checked:

• agentless-scanning/onboard-accounts/onboard-azure - See agentless-scanning/onboard-accounts/onboard-azure at the bottom of the page.
• agentless-scanning/agentless-scanning-results - See onboard-accounts/frag_start-agentless-scan.adoc at the bottom of the page
• agentless-scanning/onboard-accounts/onboard-gcp - See frag_start-agentless-scan.adoc at the bottom of the page
• install/install-openshift-4 - Search for fragments/install_defender_twistcli_export_oc_4.adoc
• waas/deploy-waas/deployment-hosts - See fragments/create-waas-rule.adoc and fragments/add-app-policy.adoc

[maxakuru]

since the HTML format changed on the worker to make the include fragments, those docs were broken until republish

just republished all, seems to be working now

[iansk]

@maxakuru This still isn't completely working. This page still has the issue:

• waas/deploy-waas/deployment-hosts

[iansk]

@maxakuru Also, quick question: What's the best way to force a republish on all content?

[maxakuru]

@iansk I republished all, seems to be working now.. could you take another look?

by design we don't have a convenient button to republish all docs, since we want to be selective for performance... however there is a script in the prisma-cloud-docs repo that can be used for batch publishing:

# publish one
npm run publish:batch docs/en/compute/pcee/admin-guide/waas/deploy-waas/deployment-hosts

# publish all in specific folder
npm run publish:batch docs/en/compute/pcee/admin-guide/waas/deploy-waas/fragments/**/*

# publish all (takes ~30 mins)
npm run publish:batch docs/**/*

[iansk]

@maxakuru Awesome, that's good stuff. Thanks for providing the script

[iansk]

@maxakuru I'm still seeing issues with this. If I grep through the doc content for include::, and check each page, I'm finding issues with virtually every page.

As an example, these pages still show the issue. I'm not sure if was previously fixed, and now showing up again. But currently, the latest published content shows the issue:

• agentless-scanning/onboard-accounts/onboard-azure - See agentless-scanning/onboard-accounts/onboard-azure at the bottom of the page.
• agentless-scanning/agentless-scanning-results - See onboard-accounts/frag_start-agentless-scan.adoc at the bottom of the page
• agentless-scanning/onboard-accounts/onboard-gcp - See frag_start-agentless-scan.adoc at the bottom of the page
• install/install-openshift-4 - Search for fragments/install_defender_twistcli_export_oc_4.adoc

[maxakuru]

@iansk these are because we changed the rules for document naming to normalize paths, but didn't change the content of the documents to correctly reference those new names.

• for the first 3 issues: frag-start-agentless-scan is being included as frag_start-agentless-scan
• for the last: install-defender-twistcli-export-oc-4 is being included as install_defender_twistcli_export_oc_4

for each of these we just need to replace the _ with -.. does that help?

[iansk]

@maxakuru Yes, that helps, thanks. I updated the underscore to a dash, but it's still not working completely working for me. Also, I now see some HTML code being rendered on the page.

Franklin preview:

https://main--prisma-cloud-docs-website--hlxsites.hlx.page/prisma/prisma-cloud/en/compute/pcee/admin-guide/agentless-scanning/onboard-accounts/onboard-azure?branch=ian/fix-include

GitHub pull request:

hlxsites/prisma-cloud-docs#69

BTW, our embedded Gdocs stopped working since you merged some recent fixes. I see the same weird HTML code on the page, so it may be related to this issue.

• https://redesign--prisma-cloud-docs-website--hlxsites.hlx.page/prisma/prisma-cloud/en/compute/pcee/admin-guide/welcome/launch?branch=ian-complex-gdoc
• https://redesign--prisma-cloud-docs-website--hlxsites.hlx.page/prisma/prisma-cloud/en/compute/30-xx/admin-guide/welcome/field-guide?branch=ian-complex-gdoc2

[maxakuru]

@iansk yep my bad, I forgot to merge a fix for a typo yesterday, fix was merged in hlxsites/prisma-cloud-docs#70

[iansk]

@maxakuru Thanks, the gdocs are loading again now. But the include:: macro still isn't working:

https://main--prisma-cloud-docs-website--hlxsites.hlx.page/prisma/prisma-cloud/en/compute/pcee/admin-guide/agentless-scanning/onboard-accounts/onboard-azure?branch=ian/fix-include

I tried republishing the page, but nothing changed.

When I inspect the element on the page, I see it's rendered (incorrectly) as a link:

<div>
<a href="https://main--prisma-cloud-docs-website--hlxsites.hlx.page/prisma/prisma-cloud/docs/en/compute/pcee/admin-guide/agentless-scanning/onboard-accounts/frag-start-agentless-scan?branch=ian%2Ffix-include" title="frag-start-agentless-scan.adoc">frag-start-agentless-scan.adoc</a>
</div>

[maxakuru]

looks like this was an error during fragment loading that only occurred when the branch query param was set

should be fixed in #142, could you try again @iansk

[iansk]

@maxakuru I'm still not seeing include:: content being loaded.

Example pages:

• https://main--prisma-cloud-docs-website--hlxsites.hlx.page/en/compute-edition/30-xx/admin-guide/waas/deploy-waas/deployment-containers?branch=ian-update-compute-ag-30
• https://main--prisma-cloud-docs-website--hlxsites.hlx.page/en/compute-edition/30-xx/admin-guide/agentless-scanning/onboard-accounts/onboard-aws?branch=ian-update-compute-ag-30
• https://main--prisma-cloud-docs-website--hlxsites.hlx.page/en/compute-edition/30-xx/admin-guide/alerts/jira?branch=ian-update-compute-ag-30

[maxakuru]

@iansk looking at logs and I see [worker] book is undefined, path resolution may fail for these

also on main I don't see a 30-xx folder: https://github.com/hlxsites/prisma-cloud-docs/tree/main/docs/en/compute-edition

remember that the book.yml needs to exist on main before the pages will work