backstage
Asciidoc Techdocs support
Hello,
we have our complete domunentation of microservices in adoc format. Would it be possible to add adoc format instead of just markdown using mkdocs.
One of the solution for us would be using our generated html from adoc (we are able to do it in our CI/CD)
Feature Suggestion
Asciidoc support
Possible Implementation
Context
We would like to serve our html generated from our asciidocs
We are also currently looking into adopting Backstage and have existing adoc documentation. We are trying to compare Backstage + referncing Antora vs what could be possible with pure Backstage Techdocs.
Serving the HTML would indeed help us, even as an interim
@tomb50 we're in the exact same position. Antora, but others want to move to backstage. Backstage is great, but being dependent on markdown is quite terrible. There are several PRs that have been closed that would have accomplished this, maybe we can take them and add the support ourselves, since it seems like they're in no rush to add it. https://github.com/backstage/backstage/pull/9385
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
Same. Asciidoc is the default for spring-rest-docs and a majority of spring documentation is in asciidoc as far as I'm aware so it's a better option than markdown IMO.
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
I also had this requirement, but worked around it by generating html with no stylesheet [1] and an antora ui that only produces body html, then renaming the html files as '.md', mkdocs was fine with the result
[1] https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
As a POC, I created a s3 proxy plugin to serve static documentation (storybook, ex_doc, ....) directly from backstage and avoid modifying the build to fit with TechDocs system.
@pwright @StephaneRob, can you both describe your solutions in a bit more detail to allow others to try and get it working as well? I think it would be highly appreciated.
Ok, I tried to do what they mentioned above, this is the solution I came up with.
build.gradle.kts
import org.asciidoctor.gradle.jvm.AsciidoctorTask // had to command click this after syncing to jump to the source and then intellij was able to find it
plugins {
// ...
id("org.asciidoctor.jvm.convert") version "4.0.1"
}
tasks.named<AsciidoctorTask>("asciidoctor") {
outputOptions {
backends("html5", "docbook")
}
sourceDir("docs/modules/ROOT")
resources(delegateClosureOf<CopySpec> {
from("docs/modules/ROOT/pages/resources") {
include("*.png")
include("**/*.png")
}
into("./resources")
})
options(mutableMapOf("standalone" to false))
copyResourcesOnlyIf("html5")
useIntermediateWorkDir()
asciidoctorj {
modules {
diagram.use()
}
}
doLast {
copy {
from("build/docs/asciidoc/html5")
into("docs/generated-html/")
rename("""(.*).html""", "$1.md")
}
}
}
My original directory structure looked like this
where all my antora docs and backstage component yamls are together.
My mkdocs.yml looks like this
docs/mkdocs.yml
site_name: 'mysite'
nav:
- Home: index.md
- Contributing: Contributing.md
- Quarkus Base Docs: quarkuks-base-docs.md
docs_dir: generated-html
plugins:
- techdocs-core
where I set the docs_dir to a generated directory.
The standalone option must be set to false for this to work.
options(mutableMapOf("standalone" to false))
The diagrams setup allows mermaid image generation to work.
If you are generating only a single backend (backends("html5")), then the asciidoc output won't have any nested html5 folder, so you'll need to update the doLast
from("build/docs/asciidoc")
Result
Footnotes even work properly!
Issues
For some reason, the pages that aren't the main index.md prepend their file name when searching for the resources. Therefore a path like this in the markdown
Contributing.md
<div class="imageblock">
<div class="content">
<img src="resources/image-2024-01-05-11-48-24-747.png" alt="image 2024 01 05 11 48 24 747">
</div>
</div>
results in a path like this in the generated docs in backstage:
<div class="imageblock">
<div class="content">
<img alt="image 2024 01 05 11 48 24 747" src="https://backstage.com/api/techdocs/static/docs/default/component/tax-service/Contributing/resources/image-2024-01-05-11-48-24-747.png">
</div>
</div>
while the same exact style html in the generated index.md docs looks like this:
<div class="imageblock">
<div class="content">
<img alt="image 2023 12 28 14 43 56 266" src="https://backstage.com/api/techdocs/static/docs/default/component/tax-service/resources/image-2023-12-28-14-43-56-266.png">
</div>
</div>
Clearly these resources will never be found. I'm not sure what to do about this. I don't really want to just copy this resources directory around to all the subpaths for no reason. This seems like a backstage bug.
@snowe2010 glad to see it worked out. TLDR; for folks rename("""(.*).html""", "$1.md") allowed Tyler to insert rendered AsciiDoc into mkdocs.
On my side, I wanted to serve static documentation without modifying them. For this I did the following:
- Build a front end plugin to add an entity route. This view has a selector to choose the doc to load for a given component and an iframe to load it (backend plugin routes)
- Build a back end plugin with a catch all route to load html, css, js, font...proxying request to s3 bucket. (with a redis cache)
I needed:
- to have a convention of where i store my static doc
- make sure that assets are loaded with the correct url to proxy request to s3 using the same catch all route than the initial html
More work but can embed any type of static doc inside backstage component.
@StephaneRob are you still able to leverage the search functionality within Backstage in your s3 POC?
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
Thanks to everyone to keep this issue open. We would also still use this feature in our project.
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
