';
- }
- resultdiv.append(searchitem);
- }
- });
-});
diff --git a/_plugins/generate_links.rb b/_plugins/generate_links.rb
index a0b348f2..3f0e4e57 100644
--- a/_plugins/generate_links.rb
+++ b/_plugins/generate_links.rb
@@ -144,6 +144,11 @@ def generate_links(page, ids, titles)
end # class LinkGen
end # module jekyll
+# 1st pass (must be the first one, so this is a separate run in the CI build !!!)
+#
+# This is used now to
+# - generate all the page, heading, and named anchor links to `${PROJECT_ROOT}/_data/links/`
+#
Jekyll::Hooks.register :site, :post_render do |site|
puts ""
shoud_build_links = (ENV['JEKYLL_BUILD_LINKS'] == 'yes')
diff --git a/_plugins/generate_tooltips.rb b/_plugins/generate_tooltips.rb
index 2be2b1ba..96ec64ee 100644
--- a/_plugins/generate_tooltips.rb
+++ b/_plugins/generate_tooltips.rb
@@ -47,39 +47,61 @@ def prefixed_url(url, base_url)
return url
end
+ def is_modifiable_markdown_part?(part)
+ # NOTE: This allows usage of our custom markdown notation in the other (h2-h6) headings as well.
+ # Unlike in the case of the page titles (h1), the (lunr) search will work nicely for the text parts.
+ return part.start_with?('[[') || part.start_with?('#')
+ end
+
def make_tooltip(page, page_links, id, url, match)
- match_parts = match.split(/\|/)
+ match_parts = match.split(/(? 1
#puts "match_parts: #{match_parts}"
- match = match_parts[0]
+ title = match_parts[0]
+ if title.length <= 0
+ puts "Error: Empty title in matching part: '#{match}' -> #{match_parts}"
+ # nil means, show the original markdown part, instead of a half rendered one
+ return nil
+ end
id = match_parts[1]
+ # This is a special use case [[title|-]] that protects the given title from further processing
+ if id == '-'
+ # Just use the original title text
+ return title
+ end
link_data = page_links[id]
if link_data != nil
url = link_data["url"]
url = prefixed_url(url, page.site.config["baseurl"])
else
- puts "Error: Unknown ID in matching part: #{match_parts}"
- return match
+ puts "Error: Unknown ID in matching part: '#{match}' -> #{match_parts}"
+ # nil means, show the original markdown part, instead of a half rendered one
+ return nil
end
+ else
+ title = match
end
if id == nil or id.length <= 0
- puts "Error: Empty ID in matching part: #{match}"
- return match
+ puts "Error: Empty ID in matching part: '#{match}' -> #{match_parts}"
+ # nil means, show the original markdown part, instead of a half rendered one
+ return nil
end
if url == nil or url.length <= 0
- puts "Error: Empty URL for ID: #{id} in matching part: #{match}"
- return match
+ puts "Error: Empty URL for ID: '#{id}' in matching part: '#{match}' -> #{match_parts}"
+ # nil means, show the original markdown part, instead of a half rendered one
+ return nil
end
# NOTE: Now we treat every link that has protocol prefix part as an external one
# that allows usage of direct links anywhere if needed (not recommended, plz use external_links.yml instead)
# but, at the same time requires e.g. all the really external links to be fully qualified (even in external_links.yml as well)
external_url = is_prefixed_url?(url)
- match = save_from_markdownify(match)
- replacement_text = '' + match + ''
+ title = save_from_markdownify(title)
+ replacement_text = '' + title + ''
# puts "replacement_text: " + replacement_text
return replacement_text
@@ -102,11 +124,15 @@ def process_markdown_part(page, markdown_part, page_links, full_pattern, id, url
left_separator = $1
matched_text = $2
right_separator = $3
- #puts "\nmatch: #{match}\nleft_separator: #{left_separator}\nmatched_text: #{matched_text}\nright_separator: #{right_separator}"
+ # puts "\nmatch: #{match}\nleft_separator: #{left_separator}\nmatched_text: #{matched_text}\nright_separator: #{right_separator}"
replacement_text = make_tooltip(page, page_links, id, url, matched_text)
- if add_separator
- replacement_text = left_separator + replacement_text + right_separator
+ if replacement_text != nil
+ if add_separator
+ replacement_text = left_separator + replacement_text + right_separator
+ end
+ else
+ replacement_text = markdown_part.gsub(/(?title tooltips/links)
+ # Content outside of Markdown blocks, aka. pure text
# Search for known link titles
# NOTE: Using multi line matching here will not help either if the pattern itself is in the middle broken/spaned to multiple lines, so
# using whitespace replacements now inside the patter to handle this, see above!
+ # NOTE: Also excludes the reqursively self added title tooltips/links
full_pattern = /(^|[\s.,;:&'"(])(#{pattern})([\s.,;:&'")]|\z)(?![^<]*?<\/a>)/
markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, true)
else
- # Content inside of special Markdown blocks
+ # Content inside of Markdown blocks
- # Handle own auto\tooltip links [[title]], but NOT [[title|id]], see bellow why
- full_pattern = /(\[\[)(#{pattern})(\]\])/
- markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, false)
+ # Handle our special markdown notation autolink/tooltip links [[title]], but NOT [[title|id]], see bellow why
+ if is_modifiable_markdown_part?(markdown_part)
+ full_pattern = /(\[\[)(#{pattern})(\]\])/
+ markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, false)
+ end
end
end
+ # Handle our special markdown notation autolink/tooltip links [[title|id]]
+ # This must be a separate run, as independent from the given title, if ID is presented it will always override the title, and the title exclusion as well
if markdown_index.odd?
- # Handle own auto\tooltip links [[title|id]]
- # This must be a separate run, as independent from the given title, if ID is presented it will always override title, and title exclusion as well
- full_pattern = /(\[\[)(.+\|.+)(\]\])/
- markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, nil, nil, false)
+ # Content inside of Markdown blocks
+
+ if is_modifiable_markdown_part?(markdown_part)
+ # puts "\nmarkdown_index: " + markdown_index.to_s + "\n" + (markdown_index.even? ? "NOT " : "") + "markdown_part: " + markdown_part
+ # NOTE: The differences in the patter is intentional, allowing empty part on both sides of | allows the same flow inside process_markdown_part
+ full_pattern = /(\[\[)(.*?(? statement
+// WARNING: Even it suggests it is a kind of "default skin", but not at all !!! Default skin is the one that skins.html declares in its statement
//
@import "minimal-mistakes/skins/default"; // skin overrides
@import "minimal-mistakes"; // main partials
diff --git a/doc/_dev-guide/chapter_4/section_2/README.md b/doc/_dev-guide/chapter_4/section_2/README.md
index b037de50..0d6599f8 100644
--- a/doc/_dev-guide/chapter_4/section_2/README.md
+++ b/doc/_dev-guide/chapter_4/section_2/README.md
@@ -59,7 +59,7 @@ Like every project {{ site.product.short_name }} also uses different libraries a
* criterion
* gcc@11
-**Hint:** If you you have [[{{ site.product.short_name }} installed via brew|dev-inst-macos#installation]], as a reference, you can check the dependencies of the brew built version using `brew deps syslog-ng`
+**Hint:** If you have [[{{ site.product.short_name }} installed via brew|dev-inst-macos#installation]], as a reference, you can check the dependencies of the brew built version using `brew deps syslog-ng`
{: .notice--info}
This is how it might look like if you start from the ground:
diff --git a/doc/_doc-guide/01_Structure/README.md b/doc/_doc-guide/01_Structure/README.md
index 355767c5..aef3c3dd 100644
--- a/doc/_doc-guide/01_Structure/README.md
+++ b/doc/_doc-guide/01_Structure/README.md
@@ -14,12 +14,7 @@ Basically we follow [[jekyll|jekyll-dir-struct]] and [[minimal-mistake|mm-dir-st
│ navigation.yml
│ excluded_titles.yml
│ external_links.yml
-│
-├── _js
-│ ├── custom
-│ ├── plugins
-│ ├── vendor
-│ _main.js
+│ link_aliases.yml
│
├── _includes
│ ├── footer
@@ -27,66 +22,144 @@ Basically we follow [[jekyll|jekyll-dir-struct]] and [[minimal-mistake|mm-dir-st
│ ...
│ └── search
│
+├── _js
+│ ├── custom
+│ ├── plugins
+│ ├── vendor
+│ _main.js
+│
├── _layouts
+│
+├── _plugins
+│
├── _sass
│ └── minimal-mistakes
+│
+├── .github
+│ └── workflows
+│
├── _site
+│
├── _tools
+│
├── assets
│ ├── css
│ ├── images
│ └── js
+│
├── doc
│ ├── _admin-guide
│ ├── _dev-guide
-│ └── _doc-guide
+│ ├── _doc-guide
+│ └── site-internal
│
_config.yml
Gemfile
-LICENSE.midnight
-LICENSE.minimal-mistakes
+LICENSE.*
README.md
```
### Directories
-- _data
+- _data \
+ Contains further `_site` generation input files for navigation, link generation, exclusion, etc.
- links \
DO NOT USE!!! \
- It lives only during jekyll serving _site data, excluded from git via `.gitignore` \
- It is built based the content of the `doc` folder
+ It lives only during jekyll generatig the _site data, excluded from git via `.gitignore` \
+ It is built based the content of the `doc` folder and contains files used for autolink/tooltip generation.
- _includes \
+ This folder contains reusable and/or common html and liquid codes the final `_site` pages are using.
-- _js \
+- _js
- custom \
- To stay organized, please keep our custom scripts in this folder.
-
+ To stay organized, please keep our custom js scripts in this folder.
+ - plugins
+ - vendor
+ 3rd party js scripts used mainly by minimal-mistakes, but also keeps dependencies of our modifications as well.
+ - lunr
+ lunr is also a 3rd party dependency, it is now the default search engine, and we have a slighty modified version of its `lunr-en.js`
- _layouts \
+ The main layout files the final `_site` pages are based on. Only the really used layouts are kept, all the other default minimal-mistakes layouts wre removed.
- _sass \
+ The Jekyll Sass converter input files, container of all the styles related sheets, except the main sheet files.
- _site \
+ DO NOT USE!!! \
+ This is the generated static `_site` content container, the content of this foler will be the final HTML site.\
+ Excluded from git via `.gitignore` \
- _tools \
+ This folder contains our [[self-made helper tools|doc-own-tools]].
+
+- .github
+ - workflows \
+ The [[GitHub CI build Action|gh-syslog-ng-doc-actions]] workflow files.
-- assets \
- - css
- - images
+- assets
+ - css \
+ The `_site` main style sheet definition files which include the content of the `_sass` folder and serve as style sheet files for skinning as well. \
+ See comments in `main.scss` for more.
+ - images \
+ The `_site` image files collector folder, please keep all the used images here, and try keep them organized mainly on their collection membership.
- js \
DO NOT USE!!! \
- It lives only during jekyll serving _site data, excluded from git via `.gitignore` \
+ It lives only during jekyll serving `_site` data, excluded from git via `.gitignore` \
It is built from the content of the `_js` folder
- doc \
+ This folder contains the real content, the markdwon files, of a given documentation collection.
+ - _admin-guide \
+ Markdown source files of The syslog-ng OSE Administration Guide
+ - _dev-guide \
+ Markdown source files of the [[Developer Guide|dev-guide]]
+ - _doc-guide \
+ Markdown source files of the [[Documentation Guide|doc-guide]]
+ - site-internal \
+ Markdown and HTML source files of the none collection, mainly `_site` common, pages like the 404 page.
### Files
- _config.yml \
- [[Jekyll configuration|jekyll-config]] file
+ Our [[Jekyll configuration|jekyll-config]] file
- Gemfile \
- Jekyll and minimal-mistake [[Ruby gem|jekyll-ruby-gems]] dependencies
-- README.md \
- The project [[GitHub repository|gh-syslog-ng-doc]] landing page readme file
+ Jekyll and minimal-mistake [[Ruby gem|jekyll-ruby-gems]] dependencies
- LICENSE.* \
- All the licence files of the modules the project uses
+ All the licence files of the modules the project uses
+- README.md \
+ The project [[GitHub repository|gh-syslog-ng-doc]] landing page readme file
+- _data/navigation.yml \
+ The input yaml file of the left navigation sidebar, this is generated by the navgen tool (DO NOT EDIT, your edits will be overwritten!).
+- _data/excluded_titles.yml \
+ A list of sentences that will be excluded from the autolink/tooltip generation.
+- _data/external_links.yml \
+ Collector of all the external links we are referencing in our pages, please keep all none site cross links here.
+- _data/link_aliases.yml \
+ A link ID based collection of alias sentences that will produce the same autolink/tooltip.
+- .github/workflows/jekyll-gh-pages.yml \
+ The GitHub CI Action site builder Workflow file.
+- _js/main.min.js \
+ All of our separate js script files (that not embedded into HTML pages) [[pack]]ed into a min.js file, except lunr files, see bellow. (DO NOT EDIT, your edits will be overwritten!)
+- _js/lunr/lunr-en.js \
+ This is a bit modified version of the lunr script that actually generates the search result output, we use a simplfied search method, actually we reverted back from the minimal-mistakes version to the original, default one described in the lunr help.
+- _plugins/common_includes.rb \
+ A Jekyll pre_render pass plugin that inserts our common inlude files into each markdown page
+- _plugins/[[generate_links]].rb \
+ A Jekyll post_render pass plugin that generates the input link files for autolink/tooltip.
+- _plugins/[[generate_tooltips]].rb \
+ A Jekyll pre_render pass plugin that generates the autolink/tooltip HTML code based on link output files of generate_links.rb and our custom markdwon extension.
+- _plugins/[[liquify]].rb \
+ A Jekyll liquid filter plugin that can force the evaluation of a liquid expression.
+- _tools/banner.js \
+ A js script that adds a DO NOT EDIT banner to a given script file.
+- _tools/[[linkcheck]] \
+ A shell script that checks the validity and availability of the link URLs in a given link file, usually in our external_links.yml
+- _tools/[[navgen]] \
+ A shell script that generates the input navigation.yml file of our left navigation sidebar from the page titles
+- _tools/[[pack]] \
+ A shell script that produces the packed main.min.js file.
+- _tools/package.json.in \
+ The input json template file of the pack tool.
+- _tools/[[serve]] \
+ A `jekyll serve` wrapper with multiple additional features.
diff --git a/doc/_doc-guide/02_Tools/01_Self_made_tools/01_Tests/README.md b/doc/_doc-guide/02_Tools/01_Self_made_tools/01_Tests/README.md
index 8ee260b5..c2c9d672 100644
--- a/doc/_doc-guide/02_Tools/01_Self_made_tools/01_Tests/README.md
+++ b/doc/_doc-guide/02_Tools/01_Self_made_tools/01_Tests/README.md
@@ -1,21 +1,42 @@
---
title: "This's a self made tools testing page of {{ site.title }}"
# short_title can be turned off for in-title liquid testing in the nav bar, uncomment if needed
-short_title: "Self made tools testing"
+short_title: "Self made tools testing page"
id: doc-testing-page
subtitle: >-
Description\subtitle is now not different than the normal, documentation body markdown texts.
It can contain ', and other special characters ()[].*?+^$, etc., though some of them might require escaping, e.g. \\ or \|
Mentioning documentation sections (markdown ##, or HTML headings) via the exact section title text should work normally, like
Slack destination options, but the linking can be forced as well via our custom markdown [[[[Timezones and daylight saving]]]] format.
- Linking also could work with our {% include markdown_link id='doc-own-tools' title='markdown_link liquid include' withTooltip='yes' %}.
+ Linking also could work with our {% include markdown_link id='doc-own-tools' title='markdown_link liquid include' withTooltip=true %}.
One more [[destination|adm-about-glossary#bom]] id=adm-about-glossary#bom override test from subtutle.
- Macros test ${HOST}).
-# this can be tested as well, but do not send to tha final version
+ Macros test ${HOST}.
+# this can be tested as well, but do not send to the final version
search: false
+# See warning bellow, or frontmatter of doc/_doc-guide/02_Tools/02_Jekyll_extensions.md
+# why this is mandatory now for pages using raw liquid examles
+render_with_liquid: false
---
-## Tests go here
+## H2 test row
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+### H3 test row
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+#### H4 test row
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+##### H5 test row
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+###### H6 test row
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**INFO:** \{: .notice--info\} Test \
any modifications or changes, use the **flags(no-parse)** option in the
@@ -30,6 +51,35 @@ you can use the built-in parsers of {{ site.product.short_name }}. For details,
`multi line backticked
text`
+Markdown link tests
+
+1st [a source title](url1){: }
+
+2nd [a source title](url2)
+
+3rd a correct reference link declaration - \[a source url_ref\]: url3 - (hopefully totally invisible)
+
+[a source url_ref]: url3
+
+4rd a reference link declaration with a missing space after : - \[b source url_ref\]:url4 - (hopefully totally invisible)
+
+[b source url_ref]:url4
+
+5th [a source title][a source url_ref] using reference link 1
+
+6th [a source title] [a source url_ref] using reference link 1 with more than 1 space between the \[\]\[\] parts
+
+7th [b source title][b source url_ref] using reference link 2
+
+8th [source title]{ url }
+
+9th [a source]{: class="" }
+
+10th [a source title]{: class="" }
+
+11th an unknown notice block declaration (hopefully invisible too)
+{: source }
+
Soft macros (sometimes also called name-value pairs) are either
built-in macros automatically generated from the log message (for
example, ${HOST}), or custom user-created macros generated by using
@@ -61,11 +111,7 @@ options {
};
```
-## Tests of custom markdown in header [[source]] and [[with turumturum id|doc-jekyll-extensions#titleid-markdown-extension]]
-
-## Tests of liquid expression {{ site.lunr.test_text_1 }} in header of {{ site.title }}
-
----------------------
+## Tests of custom markdown in header [[source]] and [[with id|doc-jekyll-extensions#titleid-markdown-extension]]
Introduction to {{ site.product.short_name }} is a test for pages without description/subtitle, but text part between the title and the first heading which can have tooltips too this way.
@@ -79,10 +125,10 @@ Test of forced link with anchored ID part [[Install Homebrew|dev-inst-macos#home
1. Same test like above in an enumeration [[Install Homebrew|dev-inst-macos#homebrew]].
-**Hint:** Same again in a notice block [[Install Homebrew|dev-inst-macos#homebrew]]. If you you have {{ site.product.short_name }} [[installed via brew|dev-inst-macos#installation]], as a reference, you can check the dependencies of the brew built version using `brew deps syslog-ng`
+**Hint:** Same again in a notice block [[Install Homebrew|dev-inst-macos#homebrew]]. If you have {{ site.product.short_name }} [[installed via brew|dev-inst-macos#installation]], as a reference, you can check the dependencies of the brew built version using `brew deps syslog-ng`
{: .notice--info}
-Embedded [link test](https://grpc.io/docs/guides/keepalive/) from a different domain
+Embedded markdown style [link test](https://grpc.io/docs/guides/keepalive/) from a different domain
Search test for RFC-3526 and RFC-3526. (you need to turn 'search: true' on temporally in the liquid header of this test page)
@@ -112,10 +158,14 @@ Slack 'destination' options
[[[[destination]]]]
-[[destination id=bom|adm-about-glossary#bom]]
+[[destination]] forced
+
+[[destination id=bom|adm-about-glossary#bom]] different title, id=bom
[[destination|adm-about-glossary#bom]] id=bom
+[[\[\[destination|bom_id\]\]|adm-about-glossary#bom]] exact example different title, id=bom
+
[[destination|]] - \[\[destination\|\]\]
[[destination||]] - \[\[destination\|\|\]\]
@@ -132,13 +182,21 @@ destination| - destination\|
Alma [[parser]] korte
-that is a direct, html link destination test
+This is a direct, html link destination test
[[another destination|adm-about-glossary#destination]] test
-{% include markdown_link id='adm-about-glossary#destination' title='destination apostroph' withTooltip='yes' %}
+{% include markdown_link id='adm-about-glossary#destination' title='markdown_link test destination apostroph' withTooltip='yes' %}
-{% include markdown_link id="adm-about-glossary#destination" title="destination quote" withTooltip="yes" %}
+{% include markdown_link id="adm-about-glossary#destination" title="markdown_link test destination quote" withTooltip="true" %}
+
+{% include markdown_link id="adm-about-glossary#destination" title="markdown_link test withTooltip=\"yes\"" withTooltip="yes" %}
+
+{% include markdown_link id="adm-about-glossary#destination" title="markdown_link test withTooltip=yes" withTooltip=yes %}
+
+{% include markdown_link id="adm-about-glossary#destination" title="markdown_link test withTooltip=\"true\"" withTooltip="true" %}
+
+{% include markdown_link id="adm-about-glossary#destination" title="markdown_link test withTooltip=true" withTooltip=true %}
option
@@ -152,18 +210,29 @@ For more information, see
[[Options of the kafka() destination's C implementation]] or
Options of the kafka() destination's C implementation.
-
For details, see [[The syslog-ng.conf manual page]].
-## See also
+## See also direct
-[[The syslog-ng.conf manual page]]
+The syslog-ng.conf manual page
-[[The {{ site.product.short_name }} manual page]]
+[[The {{ site.product.short_name }} manual page|adm-man-syslogng]]
+
+Here comes a liquid {% raw %}\{% include doc/admin-guide/manpages-footnote.md %\}{% endraw %}
+and a {% raw %}\{\{ site.product.name \}\}{% endraw %} variable raw inclusion test
+
+One more without any escaping using the `render_with_liquid: false` frontmatter option {% raw %}{% include doc/admin-guide/manpages-footnote.md %}{% endraw %}
+and a {% raw %}{{ site.product.name }}{% endraw %} variable raw inclusion test
+
+**WARNING:** \
+Take care, this might require a special notation even if \{% raw %\} and \{% endraw %\} block should protect alone these blocks, but it does not exactly !!! \
+See the source-code of this page how to escape it correctly (otherwise the page custom rendering might break!!!) \
+We found that using the `render_with_liquid: false` frontmatter option helps best, though it is not clearly documented, and its name suggests it will supress liquid rendering entirely, but (luckily ?) with our custom rendering it supresses only the final liquid render pass (that can fully eliminate our self-rendered content otherwise)
+{: .notice--warning}
-Here comes an include doc/admin-guide/manpages-footnote.md test
{% include doc/admin-guide/manpages-footnote.md %}
+Further liquid site variable tests. \
When encoding is set in a source (using the encoding() option) and the
message is longer (in bytes) than log-msg-size() in UTF-8
representation, {{ site.product.short_name }} splits the message at an undefined
diff --git a/doc/_doc-guide/02_Tools/01_Self_made_tools/README.md b/doc/_doc-guide/02_Tools/01_Self_made_tools/README.md
index b9f5e2e8..3011170a 100644
--- a/doc/_doc-guide/02_Tools/01_Self_made_tools/README.md
+++ b/doc/_doc-guide/02_Tools/01_Self_made_tools/README.md
@@ -19,28 +19,29 @@ The most useful tool is `jekyll serve`, you can start it like `bundle exec jekyl
This will,
- live refresh the site pages which are opened in a browser page
- - handle '_config.yml' changes as well that is not supported by jekyll at the moment\
+ - handle '_config.yml' changes as well that is not supported by jekyll at the moment
Note: Unlike `--liverolad`, the latter will restart `jekyll serve` therefore will not refresh the opened web pages automatically, so you have to refresh the opend pages manually
{: .notice}
-serve can handle 3 further functionalities that can be controlled via environment variables, like
+serve handles 3 further functionalities that can be controlled via environment variables, like
```shell
JEKYLL_USE_AUTO_PACK=yes JEKYLL_BUILD_TOOLTIPS=yes JEKYLL_BUILD_LINKS=yes ./_tools/serve --host=127.0.0.1 --port=4000 --livereload-port=30000 -l -w --trace
```
-> `JEKYLL_BUILD_LINKS`, defaults to `'no'`, if set to `'yes'`, it updates the pages, and anchor links in the `${PROJECT_ROOT}/_data/links/` folder that will be used for autolink and tooltip generations
+> `JEKYLL_BUILD_LINKS`, defaults to `'no'`, if set to `'yes'` it updates the pages, and anchor links in the `${PROJECT_ROOT}/_data/links/` folder that will be used for autolink and tooltip generation
Note: This can be triggered from navgen helper tool independently as well
{: .notice}
-> `JEKYLL_BUILD_TOOLTIPS`, defaults to `'no'`, if set to `'yes'`, it will generate the autolinks and tooltips into the final _site based on the content of `${PROJECT_ROOT}/_data/links/` folder
+> `JEKYLL_BUILD_TOOLTIPS`, defaults to `'no'`, if set to `'yes'` it will generate the autolinks and tooltips into the final _site based on the content of `${PROJECT_ROOT}/_data/links/` folder
Note: This could be a very long process, so if you are not working with the autolinks or tootltips, you can leave this option turned off (it will always run in the final CI site build process)
{: .notice}
-> `JEKYLL_USE_AUTO_PACK`, defaults to `'no'`, if set to `'yes'`, it automatically invokes the pack helper tool to re-pack the `${PROJECT_ROOT}/assets/js/main.min.js` file if any changes detected in the `${PROJECT_ROOT}/_js/main.min.js` file, yes, for various reasons currently only that file is watched in the `${PROJECT_ROOT}/_js/` folder, so once you've finished your modification in it you can trigger the re-pack flow e.g. via
+> `JEKYLL_USE_AUTO_PACK`, defaults to `'no'`, if set to `'yes'` it automatically invokes the pack helper tool to re-pack the `${PROJECT_ROOT}/assets/js/main.min.js` file if any changes detected in the `${PROJECT_ROOT}/_js/main.min.js` file. \
+> Yes, for various reasons currently only that file is watched in the `${PROJECT_ROOT}/_js/` folder, so once you've finished your modification in it, or in the other packed .js files, you can trigger the re-pack flow via e.g.
```shell
touch ${PROJECT_ROOT}/_js/main.min.js
@@ -59,14 +60,14 @@ Fortunately we already have a helper to simplify this, you can invoke it like
```
This will update the `navigation.yml` file based on the content of the `${PROJECT_ROOT}/_doc` folder where all of our doumentation markdown files are located. \
-`navgen` accepts 2 further, anonymous 'boolean' options, both can be `'yes'` to turn it on, or anything else e.g. `'no'` to turn it off
+`navgen` accepts 2 further, anonymous 'boolean' options, both can be `'yes'` to turn it on, or anything else (e.g. `'no'`) to turn it off
-> 1. param, defaults to `'yes'`, sets value of `JEKYLL_BUILD_LINKS` env variable, if set to `'yes'`, it updates the pages, and anchor links in the `${PROJECT_ROOT}/_data/links/` folder.
-> 2. param, defaults to `'no'`, sets value of `JEKYLL_BUILD_TOOLTIPS` env variable, if set to `'yes'`, it runs `jekyl build` to test building of the autolinks and tooltips, see serve for more.
+> 1. param, defaults to `'yes'`, sets value of `JEKYLL_BUILD_LINKS` env variable, if set to `'yes'` it updates the pages, and anchor links in the `${PROJECT_ROOT}/_data/links/` folder.
+> 2. param, defaults to `'no'`, sets value of `JEKYLL_BUILD_TOOLTIPS` env variable, if set to `'yes'` it runs `jekyl build` to test building of the autolinks and tooltips, see serve for more.
The serve tool can handle these as well automatically, see there.
-Important: This tools is part of the GitHub deployment workflow too, so any modification you add to `${PROJECT_ROOT}/_data/navigation.yml` file or `${PROJECT_ROOT}/_data/links` folder will be lost during the site build.
+Important: This tools is part of the GitHub deployment workflow too, so any modification you add to its output, either to the `${PROJECT_ROOT}/_data/navigation.yml` file or `${PROJECT_ROOT}/_data/links` folder, will be lost during the site build.
{: .notice--danger}
## pack
@@ -81,7 +82,7 @@ After updated the given dependency .js file you can simply run
```
It will update the `${PROJECT_ROOT}/assets/js/main.min.js` file that will be built and deployed normally in the next dev cycle. \
-pack can accept a single parameter that can be anything, if it recieves at least one parameter it will produce a beautified, human-readable `main.min.js` file.
+pack can accept a single parameter that can be anything (e,g, `debug`), if it recieves at least one parameter it will produce a beautified, human-readable `main.min.js` file.
Important: This tools is also part of the GitHub deployment workflow, so any modification you add to `${PROJECT_ROOT}/assets/js/main.min.js` will be lost during the site build. \
All the files in the `js` folder, except the ones in the `js/custom` folder, are presented here to get the re-packing work. \
@@ -89,17 +90,9 @@ Packing all the requirements that really needed is not supported yet, please see
So, only these default files will be packed at the moment, this is the inherited defult of Minimal Mistakes, if you have to modify these, please try to minimize the further dependencies otherwise the packing might not work anymore.
{: .notice--danger}
-Note: There were multiple issues we could not deal with yet during re-packing and those are postponed for later examination. You can find some info about this in the script file, please feel free to contribute if you have a solution.
+Note: There were multiple issues we could not deal with yet during re-packing and those are postponed for later investigation. You can find some info about this in the script file, please feel free to contribute if you have a solution.
{: .notice}
-## Jekyll extensions, plug-ins
+## linkcheck
-1. markdown_link
-
-1. liquify
-
-1. generate_links
-
-1. generate_tooltips
-
-1. \[\[title\|id\]\]
+This shell script helps to check and keep up to date our `external_links.yml` file (or any other, similar yaml files with url: keys), it validates all the URLs, trying to open them via `curl` and display a warning if an error code recieved during the fetch attempt of the page pointed by the URL.
diff --git a/doc/_doc-guide/02_Tools/02_Jekyll_extensions.md b/doc/_doc-guide/02_Tools/02_Jekyll_extensions.md
new file mode 100644
index 00000000..4eaeb5e9
--- /dev/null
+++ b/doc/_doc-guide/02_Tools/02_Jekyll_extensions.md
@@ -0,0 +1,247 @@
+---
+title: Jekyll extensions, plug-ins
+id: doc-jekyll-extensions
+description: >-
+ Jekyll is felxible and extendable, accepts various [[plugins|jekyll-plugins]], liquid or markdown extensions, and we are using a bit of all of them.
+# Take care, using liquid examples in a liquid rendered page might require a special notation even if {% raw %} and {% endraw %} block should protect alone these blocks (https://jekyllrb.com/docs/liquid/tags/), but it does not exactly !!!
+# See the _doc-guide/02_Tools/01_Self_made_tools/01_Tests/README.md page how can escape it correctly in some cases (otherwise our custom page rendering might break!!!)
+# We found that using the `render_with_liquid: false` frontmatter option helps best, though it is not clearly documented, and its name suggests it will supress liquid rendering entirely, but (luckily ?) with our custom rendering (_plugins/generate_tooltips.rb) it supresses only the final liquid render pass (absence of `render_with_liquid: false` can fully eliminate our self-rendered content otherwise)
+render_with_liquid: false
+---
+
+## markdown_link
+
+This pure liquid include file can be used to generate markdown links from the links created by our generate_links plugin with various additionsl parameters.
+
+It can declare
+
+``` liquid
+{% raw %}[ref:{{ md_link_id }}]: {{ md_link_url | relative_url }}{% endraw %}
+```
+
+or define
+
+``` liquid
+{% raw %}[{{ md_link_title }}]({{ md_link_url | relative_url }}){: {{ md_link_style }} }{% endraw %}
+```
+
+a markdown link, where the link url and title is handled automatically using the given ID.
+
+Please note that the url and the default title text must not be provided here (though can be overriden if needed), the lookup of them will be automatic based on the given ID, the generate_links collected links in the `${PROJECT_ROOT}/_data/links` folder are also available via the `site.data.links` liquid variable, markdown_link uses this variable as well to search for the given ID and the corresponding title and url.
+{: .notice}
+
+You can use the following parameters to adjust the composition of the above `md_link_` options:
+
+- `decl`, a boolean string `'yes'`, `'no'` or value `true`, `false` that controls if the generated link is a declaration, or definition, e.g.:
+
+ ``` liquid
+ {% raw %}{% include markdown_link id='id' decl=true %}{% endraw %}
+ ```
+
+ markdown output
+
+ ``` markdown
+ [ref:id]: url
+ ```
+
+ that you can use later like
+
+ ``` markdown
+ [custom title][ref:id]
+ ```
+
+- `id`, the link ID, e.g.:
+
+ ``` liquid
+ {% raw %}{% include markdown_link id='id' %}{% endraw %}
+ ```
+
+ markdown output
+
+ ``` markdown
+ [title](url){: class="nav-link" }
+ ```
+
+ Please note that the `class="nav-link"` style is always added to the link, except if `outOfFrame` is set to `yes`
+ {: .notice}
+
+- `title`, a custom title that can override the one that belongs to the given link ID, e.g.:
+
+ ``` liquid
+ {% raw %}{% include markdown_link id='id' title='custom title' %}{% endraw %}
+ ```
+
+ markdown output
+
+ ``` markdown
+ [custom title](url){: class="nav-link" }
+ ```
+
+- `withTooltip`, a boolean string `'yes'`, `'no'` or value `true`, `false` that controls if the genrated link should have css class style that is treated as [[autolink/tooltip]], e.g.:
+
+ ``` liquid
+ {% raw %}{% include markdown_link id='id' withTooltip=true %}{% endraw %}
+ ```
+
+ markdown output
+
+ ``` markdown
+ [title](url){: class="nav-link content-tooltip" }
+ ```
+
+ generate_tooltips will use the `content-tooltip` class to generate autolink/tooltip.
+
+- `newPage`, a boolean string `'yes'`, `'no'` or value `true`, `false` that controls if a navigational click on the generated final HTML anchor element will open the link in a new browser tab, or window, e.g.:
+
+ ``` liquid
+ {% raw %}{% include markdown_link id='id' newPage=true %}{% endraw %}
+ ```
+
+ markdown output
+
+ ``` markdown
+ [title](url){: class="nav-link" target="_blank" }
+ ```
+
+- `outOfFrame`, a boolean string `'yes'`, `'no'` or value `true`, `false` that controls if a navigational click on the generated final HTML anchor element will open the linked content in the right frame of the page, or will trigger a full page load that replacing the current content entirely, e.g.:
+
+ ``` liquid
+ {% raw %}{% include markdown_link id='id' outOfFrame=true %}{% endraw %}
+ ```
+
+ markdown output
+
+ ``` markdown
+ [title](url){: }
+ ```
+
+ Please note the absence of the `class="nav-link"` style, that will not be added if outOfFrame is `true`
+ {: .notice}
+
+## liquify
+
+liquify.rb is a nice liquid filter that parses liquid objects to their actual value, it is useful e.g. places wehre it is not happening automatically f.e. in [[page titles|liquify-rb]].
+
+## generate_links
+
+Our generate_links.rb Jekyll plugin creates the content of the `${PROJECT_ROOT}/_data/link` folder. The generated link files are created from all the H1-H6 headings, named anchors, and the page self-links of our markdown pages. The links are used for autolink/tooltip generation and page navigation ordering.
+
+## generate_tooltips
+
+The generate_tooltips.rb Jekyll plugin is responsible for adding autolink/tooltip items to our pages. It uses multiple [[page render hook|jekyll-render-hooks]] pases, please see the source-code why it is needed. It is far-far not optimal, makes the whole rendering process very slow now and needs enhancements badly, please feel free to contribute to make it more effective!
+
+## \[\[title\|id\]\] markdown extension
+
+The generate_tooltips plugin can interpret this format of markdown linking. It accepts the following formats
+
+- `[[title]]`
+ This can force autolink/tooltip generation to use the encapsulated `title` string for title matching. This can be useful when the given title is part of a longer title sentence that otherwise will be used for the autolink/tooltip composition. \
+ In the following sentence
+
+ ``` text
+ The syslog-ng OSE darwin-oslog() source options explains how you can configure the new native macOS sytem log source.
+ ```
+
+ the darwin-oslog() source options normally will become an autolink/tooltip, as we have a page with this title which its own link is part of the `${PROJECT_ROOT}/_data/links` collection produced by generate_links, therefore will be transformed automatically to an autolink/tooltip by generate_tooltips.
+
+ Using
+
+ ``` text
+ The [[syslog-ng OSE]] darwin-oslog() [[source]] options explains how you can configure the new native macOS sytem log source.
+ ```
+
+ the syslog-ng OSE and the source will become an autolink/tooltip instead.
+
+- `[[title|id]]`
+ This can force autolink/tooltip generation to use a different `title` string for a given link `id`, or a different `id` (that way the link belongs to that `id`) for a given `title` string. This can be useful when the given title is ambigous in a given context, and one would like to force the generated autolink/tooltip point to a (different) specific location. \
+ In the following sentence
+
+ ``` text
+ The syslog-ng OSE darwin-oslog() [[source|adm-src-macos]] is a new native macOS sytem log source.
+ ```
+
+ the first occrence of `source` will become an autolink/tooltip to the `admin-guide/060_Sources/085_macOS/README.md` page, whilst the second one will point to the default `admin-guide/200_About/002_Glossary#source`.
+
+- `[[title|-]]`
+ This is a special case which can be useful in a given context to temporally disable the generation of an autolink/tooltip, using this form the `title` text will not be touched at all, e.g.
+
+ ``` text
+ This can lead to the [[source|-]] of a misunderstanding.
+ ```
+
+ will produce
+
+ This can lead to the [[source|-]] of a misunderstanding.
+
+ without any autolink/tooltip generated (as in this context pointing to the default `admin-guide/200_About/002_Glossary#source` page is meaningless, and confusing).
+
+- Any other combination with a missing `title` or `id` leads to an error message during build time and keeps the original special markdown part in the HTML output to signal the error visually as well, e.g.
+
+ ``` text
+ This can lead to the [[source|]] markdown reflected back in the final HTML output.
+ ```
+
+ will produce
+
+ This can lead to the [[source|]] markdown reflected back in the final HTML output.
+
+**A small cross-reference table of the use cases**
+
+| \[\[ case \]\] | found | success | result|
+|-------------------|--------------|-------------|----------------------------------------|
+| \[\[title\|id\]\] | id found | ok | the title text transformed to autolink/tootlip, its autolink/tooltip created based by id and the url belongs to that id |
+| \[\[title\|id\]\] | id not found | error msg | the markdown is included into the HTML output |
+| \[\[title\]\] | found | ok | the title text transformed to autolink/tootlip, its autolink/tooltip created based by the id of the first matching title in the link collection created by generate_links, and the url belongs to the found id |
+| \[\[title\]\] | not found | error msg | the markdown is included into the HTML output |
+| \[\[title\|-\]\] | n/a | ok | the exact title text without any modification |
+| \[\[title\|\]\] | n/a | error msg | the markdown is included into the HTML output |
+| \[\[\|id\]\] | n/a | error mg | the markdown is included into the HTML output |
+
+**Example results of above cases from top down**
+
+existing [[id with title|doc-jekyll-extensions]] test
+
+unknown [[id|unknown-id]] test
+
+forced existing [[source]] test
+
+forced none existing [[title]] test
+
+forced original text [[source|-]] test
+
+empty [[id|]] test
+
+empty title [[|doc-jekyll-extensions]] test
+
+## autolink/tooltip
+
+This enhancement allows us to create automatic links and Wikiwand like tooltips (previews of linked articles) in the markdown documentation pages to
+
+- other local pages, based on their title text [h1 heading]
+- headings [h2-h6] of any local pages, based on the heading text
+- named anchors of any local pages, based on the anchor text
+- any of the above, via given text parts that enumerated in the `${PROJECT_ROOT}/_data/link_aliases.yml` file
+- any of the above, via given text parts that marked using our custom markdown notation
+- any of the above, via our markdown_link liquid include
+- external pages, via given text parts enumerated in the `${PROJECT_ROOT}/_data/external_links.yml` file
+
+The automatic link and tooltip generation primarily use one-to-one text matching of the given text in the above enumerated cases to the markdown content, from the longest sentence to the shortest one. You can exclude specific sentences from the process using `${PROJECT_ROOT}/_data/excluded_titles.yml`.\
+These can all be overridden by using the [[\[\[title|id\]\] markdown extension|doc-jekyll-extensions#titleid-markdown-extension]], which always has priority over these rules (even over the exclusions!).
+
+The basic flow is as follows:
+
+- in the first site generation pass
+ - the Jekyll liquid parser creates named anchors from our markdown_link liquid includes
+ - the generate_links tool creates the input links in the `${PROJECT_ROOT}/_data/links/` folder from all the page links, [h2-h6] headings, and named anchors of the pages
+
+- in the second site generation pass, the generate_tooltips tool
+ - builds a link dictionary from all the page links of `${PROJECT_ROOT}/_data/links/` folder sorted by title length in reverse order
+ - adds aliases to the given titles in the link dictionary from the `${PROJECT_ROOT}/_data/link_aliases.yml`
+ - excludes titles from the link dictionary based on the content of the `${PROJECT_ROOT}/_data/external_links.yml` file
+
+- in the third site generation pass, the generate_tooltips tool
+ - finalizes the left navigation sidebar content from `${PROJECT_ROOT}/_data/navigation.yml`
+ - generates the HTML code from the link dictionary for the autolinks and tooltips
+
+- at runtime
+ - .js code parts adds the tooltip code to the named anchors with specific autolink, tooltip class(es)
diff --git a/doc/site-internal/lunr_search_help.md b/doc/site-internal/lunr_search_help.md
index cfc95c2f..7f84e8ff 100644
--- a/doc/site-internal/lunr_search_help.md
+++ b/doc/site-internal/lunr_search_help.md
@@ -26,12 +26,6 @@ foo bar
The above example will match documents that contain either “foo” or “bar”. Documents that contain both will score more highly and will be returned first.
-## Scoring
-
-The score (also known as relevance) of a document is calculated by the BM25 algorithm, along with other factors such as boosts. You don’t need to worry too much about the details of how BM25 works; to summarize, the more a search term occurs in a single document, the more that term will increase that document’s score, but the more a search term occurs in the overall collection of documents, the less that term will increase a document’s score.
-
-For example, let’s say you’re indexing a collection of documents about JavaScript testing libraries. The terms “JavaScript”, “library”, and “test” may occur very frequently throughout the entire collection, so finding a document that mentions one of these terms isn’t very significant. However, if you’re searching for “integration test”, only three documents in the collection have the term “integration” in them, and one of them mentions “integration” many times, that will bring the score for that one document higher up.
-
## Wildcards
Lunr supports wildcards when performing searches. A wildcard is represented as an asterisk (*) and can appear anywhere in a search term. For example, the following will match all documents with words beginning with “foo”:
@@ -113,3 +107,9 @@ foo~1
```
An edit distance of 1 allows words to match if either adding, removing, changing or transposing a character in the word would lead to a match. For example “boo” requires a single edit (replacing “f” with “b”) and would match, but “boot” would not as it also requires an additional “t” at the end.
+
+## Scoring
+
+The score (also known as relevance) of a document is calculated by the BM25 algorithm, along with other factors such as boosts. You don’t need to worry too much about the details of how BM25 works; to summarize, the more a search term occurs in a single document, the more that term will increase that document’s score, but the more a search term occurs in the overall collection of documents, the less that term will increase a document’s score.
+
+For example, let’s say you’re indexing a collection of documents about JavaScript testing libraries. The terms “JavaScript”, “library”, and “test” may occur very frequently throughout the entire collection, so finding a document that mentions one of these terms isn’t very significant. However, if you’re searching for “integration test”, only three documents in the collection have the term “integration” in them, and one of them mentions “integration” many times, that will bring the score for that one document higher up.