guides: add Antora SSG #179
Conversation
|
Deployment has finished 👁️👄👁️ Your app is available here |
|
Thanks @davlgd I will test the tutorial and merge if nothing needs to be added to the tutorial |
| --- | ||
| [Antora](https://antora.org/) is an [AsciiDoc](https://asciidoc.org/) based Static Site Generator focused on technical documentation writing. It promotes *docs as code*, using a YAML playbook and git repositories to organize and host content. If you need an example source code, use the [demo playbook](https://docs.antora.org/antora/latest/install-and-run-quickstart/#create-a-playbook) (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)): | ||
| ```bash | ||
| git init |
There was a problem hiding this comment.
Why do we init a .git repository outside the app?
There was a problem hiding this comment.
Why outside the app ? It's the initial git init we'll need later to commit/deploy.
As mentioned here, this guide/example is based on the default playbook provided in the Antora documentation as an example.
| npm i -D -E @antora/cli @antora/site-generator | ||
| echo -e "site:\n title: Antora Docs\n start_page: component-b::index.adoc\ncontent:\n sources:\n - url: https://gitlab.com/antora/demo/demo-component-a.git\n branches: HEAD\n - url: https://gitlab.com/antora/demo/demo-component-b.git\n branches: [v2.0, v1.0]\n start_path: docs\nui:\n bundle:\n url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable\n snapshot: true" > antora-playbook.yml | ||
|
|
||
| ``` |
There was a problem hiding this comment.
- what are the flags you're using and why to you use them?
- what exactly is doing this script?
There was a problem hiding this comment.
-D is to use packages as dev dependencies. -E can be removed here as I remove the exact version (but we can also use latest version in this command if you prefer).
The echo line is to create the playbook.yml demo file which will be used to deploy
|
General overview: this guide brings more confusion than clarity about Antora deployments. It should contain more details, steps, issues that could arise in a cloud environment, etc. Overall, our SGG section is quite incomplete and misleading, guides stay superficial and reveal a drastic lack of knowledge of different framework specs, and their potential issues with our runtimes. In order to merge this guide, it should contain, at least:
|
|
I'm not sure to understand what's asked here. This guide explains mostly how to deploy a sample project (the Antora demo playbook they provide in their documentaiton) with env vars needed on our platform. Thus, the two points you're asking for are already here from my pov. I'm not aware of any issue that could arise in such a deployment. Maybe on the development side, but I don't think it's a good practice to reproduce Antora's (or any other framework) documentation in our guides. BTW these guides are a starting point (better than none) we can complete as we're asked details by users. |
|
The best thing, in my opinion, would be to add a prerequisite disclaimer on all Static Site Generator deployment pages: RequirementsThis guide assumes you are acquainted with |
How can I make this more specific?
The two points are:
You should. If you are writing a guide on deploying some technology, that should be the number one requirement before submitting any PR.
Agree to disagree |
To be honest, some software run great on local but encounter issues on Clever Cloud, as will any code running on any server that is set up differently. The goal of the guides is to fill the gap between that software running on local without any problem and the Clever Cloud servers. I agree that successfully starting it on local is a basic requirement that we should specify. |
Some tools init the local git repo during template creation, some not. As we need a git repo to deploy, I Then, I setup the npm packages and write the demo playbook (from the official documentation, linked above). I don't think such commands needs to be presented as 1-2-3 steps, but if you prefer to, feel free.
I followed here the same template as previous SSG guides where I didn't have such comment. If you will I can add a sentence/paragraph to explain what they do and a link to reference. |
|
About the "outside of the repository", I see. It's because in other SSG guides, the So tell me if you prefer:
|
|
I'm rewriting the guides (eg. this PR) because they are unclear and crowded with useless information. I would prefer not to add another guide I'd need to rewrite, they are already too many. We should discuss this on one on one and set guides standards that we both agree with. |
|
I'm more likely to think that such standards should be discussed and defined team-wide, as they'll be applied team-wide. But we can start the discussion 1-1. |
|
Let's do this |
|
What's the update on this guide? |
|
Closing this draft as it's accumulating conflicts since February and there's no progress. Re-open on a new branch or rebase the current one. |
Checklist
Pull request type
Please check the type of change your PR introduces:
Description
Add a SSG guide for Antora