From 7b8ea39b67c83a84d2e7d4e34fc8a7200fd6851a Mon Sep 17 00:00:00 2001 From: Bob Furu <47002677+bobfuru@users.noreply.github.com> Date: Fri, 6 Oct 2023 15:37:22 -0600 Subject: [PATCH] GH-53958: Fix xref guidelines for contrib doc Fix xref guidelines for contrib doc, make 1 scenario Fix xref guidelines for contrib doc, make 1 scenario GH-53958: Fix xref guidelines for contrib doc As called out in the comments: https://github.com/openshift/openshift-docs/issues/53958 This updates the `/baz/zig` and `/baz/zag` examples. @openshift/team-documentation PTAL --- contributing_to_docs/doc_guidelines.adoc | 53 ++++++++---------------- 1 file changed, 18 insertions(+), 35 deletions(-) diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc index ab5b89d9946c..439133033da1 100644 --- a/contributing_to_docs/doc_guidelines.adoc +++ b/contributing_to_docs/doc_guidelines.adoc @@ -744,56 +744,39 @@ IMPORTANT: You must use `link:` before the start of the URL. IMPORTANT: You cannot link to a repository that is hosted on www.github.com. -TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link. +TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, print the URL without adding a `[friendly text]` block at the end; it will automatically render as a link. === Links to internal content -There are two scenarios for linking to other assemblies: -1. Link to another file that exists in the same directory. -2. Link to another file that exists in a separate directory. - -The following examples use the example directory structure shown here: -.... -/ -/foo -/foo/bar.adoc -/baz -/baz/zig.adoc -/baz/zag.adoc -.... - -*Link to assembly in same directory* +If you want to link to other assemblies or modules in the repository, use the following format: ---- -xref:#anchor-id[friendly title] +xref:..//.adoc#[] ---- -You must use the `.adoc` file extension. The document processor will correctly link this to the resulting HTML file. - -For example, using the above syntax, if you are working on `zig.adoc` and want to link to `zag.adoc`, do it this way: - ----- -xref:../zag.adoc#baz-zag[comment] ----- +Note the following guidelines: -where `baz-zag` is the anchor ID at the top of the file `zag.adoc`. +* You must use the `.adoc` extension. +* You must specify an anchor ID. +* You must back up the appropriate number of levels (`../`, `../../`, and so on) to get back to the top-level `openshift-docs/` repository, and then specify the subdirectories to get back down to the assembly. -*Link to assembly in different directory* +For example, if you have the following directory structure: ----- -xref:../dir/.adoc#anchor-id[friendly title] ----- +.... +openshift-docs/ +openshift-docs/test1 +openshift-docs/test1/test2.adoc +openshift-docs/test3 +openshift-docs/test3/example1.adoc +.... -For example, if you are working on `bar.adoc` and you want to link to `zig.adoc`, do it this way: +And you are working in `test2.adoc` and want to link to `example1.adoc`, use the following xref: ---- -For more information, see the xref:../baz/zig.adoc#baz-zig[ZIG manual]. +For more information, see the xref:../test3/example1.adoc#test3-example1[EXAMPLE1 manual]. ---- -[NOTE] -==== -You must use the `.adoc` extension in order for the link to work correctly and you must specify an anchor ID. -==== +where `test3-example1` is the anchor ID. == Embedding an external file