@@ -7,6 +7,7 @@ This document is a guide for adding content to the [spine.io](https://spine.io)
77 * [ URLs in markdown] ( #urls-in-markdown )
88 * [ Rule 1] ( #rule-1----all-internal-links-must-not-start-with-a-slash )
99 * [ Rule 2] ( #rule-2----each-link-should-end-with-a-slash-to-prevent-unnecessary-redirects )
10+ * [ Variables] ( #variables )
1011 * [ Images] ( #images )
1112 * [ URLs in HTML] ( #urls-in-html )
1213* [ Navigation] ( #navigation )
@@ -44,6 +45,30 @@ There are two rules to follow:
4445| --------------------------------------| -------------------------------------|
4546| ` [Introduction](docs/introduction/) ` | ` [Introduction](/docs/introduction) ` |
4647
48+ #### Variables
49+
50+ This example shows how to use data variables and a version variable in a URL:
51+
52+ ``` markdown
53+ [ Hello World] ({{% get-site-data "repositories.examples" %}}/hello/)
54+
55+ [ Introduction] (docs/{{% version %}}/)
56+ ```
57+
58+ Will be rendered as:
59+
60+ ``` html
61+ <a href =" https://github.com/spine-examples/hello/" target =" _blank" a >
62+
63+ <a href =" /docs/1.9.0/" a >
64+ ```
65+
66+ Where:
67+
68+ * {{% get-site-data "repositories.core_jvm_repo" %}} will apply the ` core_jvm_repo `
69+ from the ` site-commons ` -> ` data/repositories.yml ` file.
70+ * {{% version %}} adds the version label of the current page -> ` 1.9.0 ` .
71+
4772### Images
4873
4974To render an image in markdown use:
@@ -70,22 +95,57 @@ When working with layout partials, URLs should be specified using the following
7095<img class =" logo" src =" {{ `img/spine-logo.svg` | relURL }}" alt =" Spine logo"
7196```
7297
98+ # Markdown pages
99+
100+ It is nice to have the following parameters on every markdown page, especially in documentation:
101+
102+ ``` markdown
103+ ---
104+ title: Getting Started in Java
105+ description: This guide shows how to start working with Spine in Java.
106+ headline: Documentation
107+ ---
108+ ```
109+
110+ Where:
111+ * ` title ` page title.
112+ * ` description ` a short summary of what this page is about. Used for SEO.
113+ * ` headline ` shown under the main navigation. If omitted, it is not rendered.
114+
115+ Optional parameters:
116+
117+ ``` markdown
118+ ---
119+ header_type: fixed-header
120+ body_class: privacy
121+ customjs: js/pages/privacy.js
122+ ---
123+ ```
124+
125+ Where:
126+ * ` header_type ` controls how the page header behaves (for example, stays fixed while scrolling).
127+ * ` body_class ` adds a CSS class to style a specific page. By default, the body class is based on the page type.
128+ * ` customjs ` loads page-specific JavaScript.
129+
73130# Navigation
74131
75132### Main navigation
76133
77134To edit navigation items, modify ` site/data/navbar.yml ` .
78- The navigation template is located at ` site/layouts/_partials/components/navbar/navigation.html ` .
135+ The navigation layout template is located at ` site/layouts/_partials/components/navbar/navigation.html ` .
79136
80137### Documentation side navigation
81138
82- The documentation side navigation can be edited in the [ SpineEventEngine/documentation] ( https://github.com/SpineEventEngine/documentation )
83- repository in the ` docs/data/docs/<version>/sidenav.yml ` file.
139+ The documentation side navigation can be edited in the [ SpineEventEngine/documentation] [ documentation-repo ]
140+ repository in the ` docs/data/docs/<version_id>/sidenav.yml ` file.
141+
142+ If it is part of a specific documentation module, it can be found in the corresponding repository
143+ at ` docs/data/docs/<module>/<version_id>/sidenav.yml ` .
84144
85145### Documentation “Next/Prev” buttons
86146
87- The “Prev”/“Next” buttons are generated automatically for all document pages.
88- The implementation is inside the [ SpineEventEngine/documentation ] ( https://github.com/SpineEventEngine/documentation ) .
147+ The “Prev”/“Next” buttons are generated automatically for all document pages based on the ` sidenav.yml ` .
148+ The implementation is inside the [ SpineEventEngine/site-commons ] [ site-commons ] .
89149
90150# Adding code samples to the site
91151
@@ -120,18 +180,18 @@ file for details.
120180# Cloak email
121181
122182The ` cloakemail ` shortcode is used to cloak emails or phone numbers from
123- spamming bots. We store all email variables in the ` site/data/spine .yml ` file.
183+ spamming bots. We store all email variables in the ` site/data/emails .yml ` file in the ` site-commons ` .
124184
125185In markdown files, use the shortcode with a provided variable from a data file, for example:
126186
127187``` markdown
128- {{< cloakemail address_variable="spine .sales_email" >}}
188+ {{< cloakemail address_variable="emails .sales_email" >}}
129189```
130190
131191or with the display text:
132192
133193``` markdown
134- {{< cloakemail address_variable="spine .sales_email" display="Contact us" >}}
194+ {{< cloakemail address_variable="emails .sales_email" display="Contact us" >}}
135195```
136196
137197# Note blocks
@@ -216,3 +276,5 @@ the entire line with background.
216276
217277[ code-fences-doc ] : https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences
218278[ syntax-highlighting-languages ] : https://gohugo.io/content-management/syntax-highlighting/#languages
279+ [ documentation-repo ] : https://github.com/SpineEventEngine/documentation
280+ [ site-commons ] : https://github.com/SpineEventEngine/site-commons
0 commit comments