[Site] Add getting-started guides as "Guides" to the web site #3550
Conversation
snazy
force-pushed
the
guides-on-site
branch
4 times, most recently
from
2b3a442 to
1aba13e
Compare
snazy
added
the
documentation
This change follows up on the [dev-mailing list discussion](https://lists.apache.org/thread/gwxn34nzvhdqdjw2bst6kwlqt8jhb91d) and adds the guides under `getting-started/` to the web site as "Guides". * The guides had to me moved from the `getting-started/` folder into the `site/content/` folder structure, because symlinks from the `site/content/` _folder_ do not work (the contents are not pulled in). * Each guide's `README.md` file has been renamed to `index.md`, added a front-matter, which instructs Hugo to that also lets Hugo include the guide in the top-level menu. * Assets for each guide are listed at the top of each guide, so users do not have to go via GitHub. * Links in the guides have been updated. * A new layout named `guides` has been added for this use case. Two changes on the Ceph guide: * updated the misplaced `yaml` type on a code snippet * renamed `.env.example` to `dot-env.example`, because files starting with a `.` are not included
dimas-b
left a comment
dimas-b
left a comment
There was a problem hiding this comment.
Good idea to host guides on the site 👍
|
|
||
| ```shell | ||
| docker compose -f getting-started/minio/docker-compose.yml up | ||
| docker compose -f site/content/guides/minio/docker-compose.yml up |
There was a problem hiding this comment.
Is it worth having "assets" downloadable from the site, when this command assumes running in a local source repo clone?
For example, the docker-compose script refers to ../assets/polaris 🤔
There was a problem hiding this comment.
The assets are just kept next to the guides. I think it would be odd to parts of one single guide scattered around different directory trees.
All guide pages refer to the "Git clone" here.
We can certainly argue about why the guides assume that the repository root and not the guide's directory is the current directory when running the guides. I think, it would be more natural to assume the guide's directory as the current one. I just refused to change that assumption in this PR. (That assumption affects #3553, which builds on this PR.)
2 participants
This change follows up on the dev-mailing list discussion and adds the guides under
getting-started/to the web site as "Guides".getting-started/folder into thesite/content/folder structure, because symlinks from thesite/content/folder do not work (the contents are not pulled in).README.mdfile has been renamed toindex.md, added a front-matter, which instructs Hugo to that also lets Hugo include the guide in the top-level menu.guideshas been added for this use case.Two changes on the Ceph guide:
yamltype on a code snippet.env.exampletodot-env.example, because files starting with a.are not included