Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GH53958: Fix xref guidelines for contrib doc #65908

Closed
wants to merge 1 commit into from
Closed

GH53958: Fix xref guidelines for contrib doc #65908

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 18 additions & 35 deletions contributing_to_docs/doc_guidelines.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:<filename>#anchor-id[friendly title]
xref:../<dir>/<assembly_name>.adoc#<anchor_id>[<section_title>]
----

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/<filename>.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

Expand Down