From e8dcc73ac62908092971573fe3bb5f2cfdc58760 Mon Sep 17 00:00:00 2001 From: Petr Bokoc Date: May 24 2021 17:00:01 +0000 Subject: Add proper partials and examples directories with usage notes --- diff --git a/modules/ROOT/examples/exampe-example.adoc b/modules/ROOT/examples/exampe-example.adoc new file mode 100644 index 0000000..fa408e4 --- /dev/null +++ b/modules/ROOT/examples/exampe-example.adoc @@ -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. diff --git a/modules/ROOT/pages/architecture.adoc b/modules/ROOT/pages/architecture.adoc index 687e4b0..0c0ba47 100644 --- a/modules/ROOT/pages/architecture.adoc +++ b/modules/ROOT/pages/architecture.adoc @@ -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. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index b890d2a..9219ee9 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -1,3 +1,5 @@ +include::partial$attributes.adoc[] + = The Pizza Project John Doe; Jane Doe :page-authors: {author}, {author_2} @@ -7,3 +9,5 @@ The Pizza Project is a useful project with a very bad name — it helps you with In fact, this is just a source template for a new piece of the Fedora Docs. image::pizza.png[Pizza] + +Last updated in {year}. diff --git a/modules/ROOT/partials/attributes.adoc b/modules/ROOT/partials/attributes.adoc new file mode 100644 index 0000000..f5420a7 --- /dev/null +++ b/modules/ROOT/partials/attributes.adoc @@ -0,0 +1 @@ +:year: 2021 diff --git a/modules/ROOT/partials/partial-example.adoc b/modules/ROOT/partials/partial-example.adoc new file mode 100644 index 0000000..0f8f1ed --- /dev/null +++ b/modules/ROOT/partials/partial-example.adoc @@ -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.