From 21bcc2ccba5be75a600195aefdd6b5bc71f2f50c Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Fri, 11 Jun 2021 22:18:15 +0200
Subject: add autosectionlabel plugin and explanation

---
 docs/documentation.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

(limited to 'docs/documentation.rst')

diff --git a/docs/documentation.rst b/docs/documentation.rst
index 7b410e95..f869922b 100644
--- a/docs/documentation.rst
+++ b/docs/documentation.rst
@@ -137,6 +137,59 @@ We use the following syntax for Headlines.
   Paragraphs
   """"""""""
 
+Cross-References
+^^^^^^^^^^^^^^^^
+
+A plugin will used to generate a reference lable of each headline.
+To reference a page or a section in the documentation use the ``:ref:``
+command.
+
+For example you want to reference the headline **VLAN** in the
+**ethernet.rst** page. The plugin generates label based on headline
+and the file path.
+
+``:ref:`configuration/interfaces/ethernet:vlan``
+
+to use a alternative Hyperlink use it this way:
+
+``:ref:`Check out VLAN<configuration/interfaces/ethernet:vlan>``
+
+handle build errors
+"""""""""""""""""""
+
+The plugin will warn on build if a headline has a duplicate name in the 
+same document. To prevent this warning you have to put a custom link on
+top of the headline.
+
+.. code-block::
+
+   Section A
+   ==========
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr
+
+   Example
+   -------
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr
+
+   Section B
+   ==========
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr
+   
+   .. _section B example:
+
+   Example
+   -------
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr
+
+
+
+
+
+
 Address space
 ^^^^^^^^^^^^^
 
-- 
cgit v1.2.3