AsciiDoc include macro isn't working

iansk commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

waas/deploy-waas/deployment-hosts

iansk commented 1 year ago

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

maxakuru commented 1 year ago

@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 commented 1 year ago

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

iansk commented 1 year ago

@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 commented 1 year ago

@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 commented 1 year ago

@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:

https://github.com/hlxsites/prisma-cloud-docs/pull/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.

maxakuru commented 1 year ago

@iansk yep my bad, I forgot to merge a fix for a typo yesterday, fix was merged in https://github.com/hlxsites/prisma-cloud-docs/pull/70

iansk commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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

Example pages:

maxakuru commented 1 year ago

@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

hlxsites / prisma-cloud-docs-website

AsciiDoc include macro isn't working #86