diff --git a/_data/external_links.yml b/_data/external_links.yml index 0b1c1eca..dcba1cf2 100644 --- a/_data/external_links.yml +++ b/_data/external_links.yml @@ -63,6 +63,11 @@ sn-blogs: url: https://syslog-ng.com/blog/ title: [ "syslog-ng blogs" ] +mm-site: + id: mm-site + url: https://mademistakes.com/work/minimal-mistakes-jekyll-theme/ + title: [ "Minimal Mistakes" ] + mm-javascripts: id: mm-javascripts url: https://mmistakes.github.io/minimal-mistakes/docs/javascript/ diff --git a/_data/navigation.yml b/_data/navigation.yml index 73a27726..83361107 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -1239,4 +1239,8 @@ doc-guide-nav: url: /doc-guide/02_Tools/README subnav: - title: "Self made helper tools" - url: /doc-guide/02_Tools/01_Our_helpers + url: /doc-guide/02_Tools/01_Self_made_tools/README + subnav: + - title: "Self made tools testing" + url: /doc-guide/02_Tools/01_Self_made_tools/01_Tests/README + subnav: diff --git a/doc/README.md b/doc/README.md index b52cb6fd..a08291b6 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,23 +9,23 @@ id: doc-center ## {% include markdown_link id="doc-guide" title="Documentation guide" outOfFrame=true %} -If you would like to help us to make our documentation better, here you can find information about {% include markdown_link id="doc-guide#how-to-contribute-to-the-documentation" title="how to contribute" outOfFrame=true %}. +If you would like to help us to make our documentation better, here you can find information about {% include markdown_link id="doc-guide#how-to-contribute-to-the-documentation" title="how to contribute" outOfFrame=true withTooltip=true %}. [![Deploy Jekyll site to Pages](https://github.com/syslog-ng/syslog-ng.github.io/actions/workflows/jekyll-gh-pages.yml/badge.svg)](https://github.com/syslog-ng/syslog-ng.github.io/actions/workflows/jekyll-gh-pages.yml) ## {% include markdown_link id="adm-guide" title="Administration guide" outOfFrame=true %} -If you are an active user of syslog-ng, start here to {% include markdown_link id="adm-guide" title="learn" outOfFrame=true %} about installation, configuration, and fine tuning syslog-ng. +If you are an active user of syslog-ng, start here to {% include markdown_link id="adm-guide" title="learn" outOfFrame=true withTooltip=true %} about installation, configuration, and fine tuning syslog-ng. ## {% include markdown_link id="dev-guide" title="Developer guide" outOfFrame=true %} -Want to add your idea, bug-fix to the fabolous syslog-ng? Take a look at our {% include markdown_link id="dev-guide" title="developer guide" outOfFrame=true %} +Want to add your idea, bug-fix to the fabolous syslog-ng? Take a look at our {% include markdown_link id="dev-guide" title="developer guide" outOfFrame=true withTooltip=true %} ## If you need help In case you have any question, comment, or feedback, you can: -* first check out our {% include markdown_link id="doc-guide#how-to-contribute-to-the-documentation" title="contribution guide" outOfFrame=true %} +* first check out our {% include markdown_link id="doc-guide#how-to-contribute-to-the-documentation" title="contribution guide" outOfFrame=true withTooltip=true %} * post your question on the syslog-ng mailing list * use our github to track all of the [[documentation issues|gh-syslog-ng-doc-issue-tracker]] diff --git a/doc/_dev-guide/chapter_0/section_3.md b/doc/_dev-guide/chapter_0/section_3.md index 1394b41f..122d8e27 100644 --- a/doc/_dev-guide/chapter_0/section_3.md +++ b/doc/_dev-guide/chapter_0/section_3.md @@ -1,12 +1,12 @@ --- title: macOS id: dev-inst-macos +description: >- + The syslog-ng application has been resurrected on macOS by our developer team. + We hope our product can be useful for Mac users who want to increase the + security of their system through reliable logging. --- -### Introduction - -The syslog-ng application has been resurrected on macOS by our developer team. We hope our product can be useful for Mac users who want to increase the security of their system through reliable logging. - At present we are not supporting macOS syslog-ng on our [[official repository|gh-syslog-ng]] on GitHub. However, you can install pre-built syslog-ng binaries from various sources or can compile yourself following [[this guide|dev-platform-build-macos#compiling-from-source]]. If you want to install syslog-ng on macOS you can use multiple packaga managers e.g. Homebrew diff --git a/doc/_doc-guide/02_Tools/01_Our_helpers.md b/doc/_doc-guide/02_Tools/01_Our_helpers.md deleted file mode 100644 index 190ccaa1..00000000 --- a/doc/_doc-guide/02_Tools/01_Our_helpers.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Self made helper tools -id: doc-own-tools ---- - -## Our helper tools for local development and testing - -We have a few useful tools in the `${PROJECT_ROOT}/_tools` folder some of them will be mentioned here, please see the content for more, or add your usefull ones if you wish. - -Important: Most of the tools are not really prepared runnig outside of their original location and environment, most of them are assuming that will be started from the `${PROJECT_ROOT}` folder, all the examples bellow are assuming the same, so please take care when using them. -{: .notice--danger} - -1. The most useful tool is `jekyll serve`, you can start it like `bundle exec jekyll serve`, but we have a script for it you can start like the original serve, e.g. - - ```shell - ./_tools/serve --host=127.0.0.1 --port=4000 --livereload-port=30000 -l -w --trace - ``` - - 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\ - - 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 - - ```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 - ``` - - a. `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 - - Note: This can be triggered from `navgen` helper tool independently as well - {: .notice} - - b. `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} - - c. `JEKYLL_USE_AUTO_PACK`, defaults to `'no'`, if set to `'yes'`, it automatically invokes the `pack` helper tool to [re-pack](#modify-and-repack-js) 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 - - ```shell - touch ${PROJECT_ROOT}/_js/main.min.js - ``` - - Note: The distribution of the required files from `${PROJECT_ROOT}/_js/` to `${PROJECT_ROOT}/assets/js/` will always happen, this flag controls only the re-packing of the `main.min.js` (as on some systems it could lead to a broken packed file, or cannot run at all e.g. because the lack of node.js installation) - {: .notice} - -2. Generating the left sidebar navigator content, the page, and anchor links, is semi-automatic yet. The navigation bar content is generated from the `${PROJECT_ROOT}/_data/navigation.yml` file that will be read by jekyll automatically during the site build process, but adding the correct content of it is our responsibility. \ - Fortunately we already have a helper to simplify this, you can invoke it like - - ```shell - ./_tools/navgen ./doc ./_data/navigation.yml - ``` - - 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 - 1. 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. 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. - {: .notice--danger} -3. Sometimes its needed to [[update|mm-js-update]] the internally used `minimal-mistakes` theme default [[.js scripts|mm-javascripts]] \ - If you modify any of the scripts packed into the `${PROJECT_ROOT}/assets/js/main.min.js` file, you have to [[re-pack|mm-js-update]] it. - You can use our, still a work in progress, but usable `pack` helper tool. - After updated the given dependency .js file you can simply run - - ```shell - ./_tools/pack - ``` - - 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. - - 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. \ - Packing all the requirements that really needed is not supported yet, please see the note bellow. - So, only these default files will be packed at the moment, this is the inherited defult of `minimal-mistake`, 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. - {: .notice} - -## Extensions, plug-ins - -1. markdown_link - -1. liquify - -1. generate_links - -1. generate_tooltips - -1. \[\[title\|id\]\] 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 new file mode 100644 index 00000000..e1817f04 --- /dev/null +++ b/doc/_doc-guide/02_Tools/01_Self_made_tools/01_Tests/README.md @@ -0,0 +1,154 @@ +--- +title: "This's a self made tools testing page" +short_title: "Self made tools testing" +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' %}.
+ One more [[destination|adm-about-glossary#bom]] id=adm-about-glossary#bom override test from subtutle.
+ Macros test ${HOST}). +search: false +--- + +## Tests go here + +**INFO:** \{: .notice--info\} Test \ +any modifications or changes, use the **flags(no-parse)** option in the +source definition, and a template containing only the **${MESSAGE}** +macro in the destination definition. +{: .notice--info} + +To parse non-syslog messages, for example, JSON, CSV, or other messages, +you can use the built-in parsers of syslog-ng OSE. For details, see +[[parser: Parse and segment structured messages]]. + +`multi line backticked +text` + +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 +the syslog-ng pattern database or a CSV-parser. The SDATA fields of +RFC5424-formatted log messages become soft macros as well. In +contrast with hard macros, soft macros are writable and can be +modified within syslog-ng OSE, for example, using rewrite rules. + +**WARNING:** \{: .notice--warning\} Test \ +for the list of hard and soft macros, see [[Hard versus soft macros]]. +{: .notice--warning} + +**DANGER:** \{: .notice--danger\} Test \ +at the location it reaches the log-msg-size() value, and discards the rest of the message. +{: .notice--danger} + +**Code block example:** + +```config +options { + stats( + freq(1) + level(1) + lifetime(1000) + max-dynamics(10000) + syslog-stats(yes) + stats() + ); +}; +``` + +--------------------- + +Introduction to syslog-ng 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. + +Developer guide is a double (page title amd section heading) example with a description/subtitle. + +[[Installing syslog-ng|adm-install]] is a forced, (also a doubled) page link title example with a description/subtitle. + +[[Self page link|doc-testing-page]] test. + +The severity of the message. `time-zone()` teszt + +parser: Parse and segment structured messages + +`parser: Parse and segment structured messages` + +discord Sending alerts and notifications to Discord + +`discord Sending alerts and notifications to Discord` + +Timezones and daylight saving + +`Timezones and daylight saving` + +Slack destination options + +[[Slack destination options]] + +`Slack destination options` + +Slack :destination options + +Slack 'destination' options + +`Options of the mqtt() destination` + +[Parse bar] + +Alma [[parser]] korte + +[[destination]] + +[[destination id=bom|adm-about-glossary#bom]] + +[[destination|adm-about-glossary#bom]] id=bom + +[[destination||]] + +[destination|] + +destination| + +[destination] + +that 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="destination quote" withTooltip="yes" %} + +message + +[[message]] + +Options is an excluded word. + +For more information, see +[[Options of the kafka() destination's C implementation]]. + +For details, see [[The syslog-ng.conf manual page]]. + +## See also + +[[The syslog-ng.conf manual page]] + +[[The syslog-ng manual page]] + +Here comes an include doc/admin-guide/manpages-footnote.md test +{% include doc/admin-guide/manpages-footnote.md %} + +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, syslog-ng OSE splits the message at an undefined +location (because the conversion between different encodings is not +trivial). + +The following is a simple configuration file for syslog-ng Open +Source Edition that collects incoming log messages and stores them +in a text file. syslog-ng Open Source Edition. + +Aliast testing e.g ${LEVEL} or ${PRIORITY} should work like ${SDATA} 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 new file mode 100644 index 00000000..b9f5e2e8 --- /dev/null +++ b/doc/_doc-guide/02_Tools/01_Self_made_tools/README.md @@ -0,0 +1,105 @@ +--- +title: Self made helper tools +id: doc-own-tools +description: >- + We have a few useful tools in the `${PROJECT_ROOT}/_tools` folder some of them will be mentioned here, + please see the content for more, or add your usefull ones if you wish. +--- + +Important: Most of the tools are not really prepared runnig outside of their original location and environment, most of them are assuming that will be started from the `${PROJECT_ROOT}` folder, all the examples bellow are assuming the same, so please take care when using them. +{: .notice--danger} + +## serve + +The most useful tool is `jekyll serve`, you can start it like `bundle exec jekyll serve`, but we have a script for it you can start like the original serve, e.g. + +```shell +./_tools/serve --host=127.0.0.1 --port=4000 --livereload-port=30000 -l -w --trace +``` + +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\ + +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 + +```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 + +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 + +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 + +```shell +touch ${PROJECT_ROOT}/_js/main.min.js +``` + +Note: The distribution of the required files from `${PROJECT_ROOT}/_js/` to `${PROJECT_ROOT}/assets/js/` will always happen, this flag controls only the re-packing of the `main.min.js` (as on some systems it could lead to a broken packed file, or cannot run at all e.g. because the lack of node.js installation) +{: .notice} + +## navgen + +Generating the left sidebar navigator content, the page, and anchor links, is semi-automatic yet. The navigation bar content is generated from the `${PROJECT_ROOT}/_data/navigation.yml` file that will be read by jekyll automatically during the site build process, but adding the correct content of it is our responsibility. \ +Fortunately we already have a helper to simplify this, you can invoke it like + +```shell +./_tools/navgen ./doc ./_data/navigation.yml +``` + +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 + +> 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. +{: .notice--danger} + +## pack + +Sometimes its needed to [[update|mm-js-update]] the internally used Minimal Mistakes theme default [[.js scripts|mm-javascripts]] \ +If you modify any of the scripts packed into the `${PROJECT_ROOT}/assets/js/main.min.js` file, you have to [[re-pack|mm-js-update]] it. +You can use our, still a work in progress, but usable `pack` helper tool. +After updated the given dependency .js file you can simply run + +```shell +./_tools/pack +``` + +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. + +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. \ +Packing all the requirements that really needed is not supported yet, please see the note bellow. +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. +{: .notice} + +## Jekyll extensions, plug-ins + +1. markdown_link + +1. liquify + +1. generate_links + +1. generate_tooltips + +1. \[\[title\|id\]\] diff --git a/doc/_doc-guide/02_Tools/README.md b/doc/_doc-guide/02_Tools/README.md index b03f41f6..2f43400d 100644 --- a/doc/_doc-guide/02_Tools/README.md +++ b/doc/_doc-guide/02_Tools/README.md @@ -12,4 +12,4 @@ id: doc-tools 2. Install bundler\ It's just a ruby gem itself too, so simply run `gem install bundle` 3. [[Install node.js|mm-javascripts]] \ - It's needed only if you have to [[modify and re-pack|doc-own-tools#modify-and-repack-js]] the site wide .js script files + It's needed only if you have to [[modify and re-pack|doc-own-tools#pack]] the site wide .js script files