1
1
// Module included in the following assemblies:
2
2
//
3
- // assembly_mod -docs-reference -ocp.adoc
3
+ // * mod_docs_guide/mod -docs-conventions -ocp.adoc
4
4
5
5
// Base the file name and the ID on the module title. For example:
6
6
// * file name: my-reference-a.adoc
7
7
// * ID: [id='my-reference-a']
8
8
// * Title: = My reference A
9
9
10
- [id='mod-docs-ocp-conventions_ {context}']
11
- = Modular Docs OpenShift Conventions
10
+ [id='mod-docs-ocp-conventions- {context}']
11
+ = Modular docs OpenShift conventions
12
12
13
13
These Modular Docs conventions for OpenShift docs build on top of the CCS
14
14
modular docs guidelines.
@@ -25,7 +25,7 @@ IMPORTANT: If some convention is duplicated, the convention in this guide
25
25
supersedes all others.
26
26
27
27
[id='ocp-ccs-conventions-{context}']
28
- == OpenShift CCS Conventions
28
+ == OpenShift CCS conventions
29
29
30
30
* All assemblies must define a context that is unique.
31
31
+
@@ -40,15 +40,15 @@ Example:
40
40
* All anchor ids must follow the format:
41
41
+
42
42
----
43
- [id='<anchor-name-with-dashes>_ {context}']
43
+ [id='<anchor-name-with-dashes>- {context}']
44
44
----
45
45
+
46
- Anchor name is _connected_ to the `{context}` using an underscore .
46
+ Anchor name is _connected_ to the `{context}` using a dash .
47
47
+
48
48
Example:
49
49
+
50
50
----
51
- [id='creating-your-first-content_ {context}']
51
+ [id='creating-your-first-content- {context}']
52
52
----
53
53
54
54
* All modules anchor ids must have the `{context}` variable.
@@ -75,7 +75,7 @@ Example comment section in a module:
75
75
----
76
76
// Module included in the following assemblies:
77
77
//
78
- // assembly_getting-started-modular- docs-ocp.adoc
78
+ // mod_docs_guide/mod- docs-conventions -ocp.adoc
79
79
----
80
80
81
81
* All modules must go in the modules directory which is present in the top level
@@ -85,16 +85,18 @@ link:https://redhat-documentation.github.io/modular-docs/[modular docs guideline
85
85
86
86
* All assemblies must go in the the relevant guide/book (MORE TO COME ON THIS).
87
87
88
- * In your modules , when you are linking to the content in other books, you must
88
+ * In your assemblies , when you are linking to the content in other books, you must
89
89
use the relative path starting like so:
90
90
+
91
91
----
92
- xref: ../architecture/additional_concepts/authorization .adoc#roles[default roles] are here .
92
+ xref:../architecture/architecture .adoc#architecture[architecture] overview .
93
93
----
94
94
+
95
- All xref links that are placed in the modules in the modules folder must begin
96
- with `../` as you are navigating into the root folder and then into the actual
97
- book/assembly.
95
+ [IMPORTANT]
96
+ ====
97
+ You must not include xrefs in modules or create an xref to a module. You can
98
+ only use xrefs to link from one assembly to another.
99
+ ====
98
100
99
101
* All modules in assemblies must be included using the following format (please replace 'ilude' with 'include'):
100
102
+
@@ -112,6 +114,7 @@ Example:
112
114
113
115
NOTE: There is no `..` at the starting of the path.
114
116
117
+ ////
115
118
* If your assembly is in a subfolder of a guide/book directory, you must add a
116
119
statement to the assembly’s metadata to use `relfileprefix`.
117
120
+
@@ -136,6 +139,7 @@ module remains the same as described in the previous bullet.
136
139
+
137
140
NOTE: This strategy is in place so that links resolve correctly on both
138
141
docs.openshift.com and portal docs.
142
+ ////
139
143
140
144
* Do not use 3rd level folders even though AsciiBinder permits it. If you need
141
145
to, work out a better way to organize your content.
0 commit comments