PR#17: Add proper partials and examples directories with usage notes - fedora-docs/template

fedora-docs / template

#17 Add proper partials and examples directories with usage notes

Merged 3 years ago by pbokoc. Opened 3 years ago by pbokoc.

fedora-docs/ pbokoc/template master into master

Add proper partials and examples directories with usage notes

Petr Bokoc • 3 years ago

e8dcc73

modules/ROOT/examples/exampe-example.adoc

file added

		`@@ -0,0 +1,9 @@`
		+ This is an example of a example file. Unlike files in `pages/`, files in this directory are not built as standalone pages, but only if they are included in a file within `pages/`. Also unlike examples,
		+ A file in this directory can be included within any file in the `pages/` directory.
		`+`
		`+ Most common use cases for examples is using output from an external script (for example, translation string statistics) in docs. You can use an external script to update the example, and when the site is rebuilt, it will show updated output.`
		`+`
		+ If you want to include this particular example somewhere, you can use the following syntax: `include::example$example-example.adoc[]`.
		+ Note the use of `example$` instead of an actual file location.
		`+`
		`+ See link:https://docs.antora.org/antora/3.0/examples-directory/[Antora docs on examples] for more information about partials.`

modules/ROOT/pages/architecture.adoc

file modified

+1 -1

		`@@ -1,3 +1,3 @@`
		`= Pizza Factory Architecture`

		`- The architecture of our pizza factory is quite simple. We bake our very expensive xref:pizza-dough.adoc[pizza dough] in a very cheap xref:pizza-oven.adoc[pizza oven]. This way, we can achieve a medicore result for a high price and a reasonable number of failures.`
		`+ The architecture of our pizza factory is quite simple. We bake our very expensive xref:pizza-dough.adoc[pizza dough] in a very cheap xref:pizza-oven.adoc[pizza oven]. This way, we can achieve a mediocre result for a high price and a reasonable number of failures.`

modules/ROOT/pages/index.adoc

file modified

		`@@ -1,3 +1,5 @@`
		`+ include::partial$attributes.adoc[]`
		`+`
		`= The Pizza Project`
		`John Doe; Jane Doe`
		`:page-authors: {author}, {author_2}`
		`@@ -7,3 +9,5 @@`
		`In fact, this is just a source template for a new piece of the Fedora Docs.`

		`image::pizza.png[Pizza]`
		`+`
		`+ Last updated in {year}.`

modules/ROOT/partials/attributes.adoc

file added

		`@@ -0,0 +1,1 @@`
		`+ :year: 2021`

modules/ROOT/partials/partial-example.adoc

file added

+15

		`@@ -0,0 +1,15 @@`
		+ This is an example of a partial file. Unlike files in `pages/`, files in this directory are not built as standalone pages, but only if they are included in a file within `pages/`. This stops fragments of pages being built and discovered by search engines.
		`+`
		+ A file in this directory can be included within any file in the `pages/` directory.
		`+`
		`+ Most common use cases for partials are:`
		`+`
		`+ . Reusing attributes such as the current year or a release version throughout the entire module while being able to change it easily (such as changing "Fedora 33" to "Fedora 34" when a new release comes out).`
		+ . Reusing content such a banner or an infobox (`[NOTE]`, etc.) that appears on multiple pages and needs to have consistent content everywhere (such as a message on some of the quick-docs that warns the reader about their unreviewed status).
		`+`
		+ In these cases, you can use a partial to include the same content in multiple places, and you only need to change it once to get the change to appear in every spot it's included in. You can see the first example used in `pages/index.adoc` in this repository; note the include statement on top.
		`+`
		+ If you want to include this particular example somewhere, you can use the following syntax: `include::partial$partial-example.adoc[]`.
		+ Note the use of `partial$` instead of an actual file location.
		`+`
		`+ See link:https://docs.antora.org/antora/3.0/partials-directory/[Antora docs on partials] for more information about partials.`

pbokoc commented 3 years ago

Antora went through plenty of updates since we first set up this repo. This PR brings the example structure up to date and provides some explanation for the partials and examples directories with links to upstream docs.