diff --git a/_data/external_links.yml b/_data/external_links.yml index 3a4dc7b1..b575ca81 100644 --- a/_data/external_links.yml +++ b/_data/external_links.yml @@ -58,6 +58,16 @@ sn-prod-binaries-dl: url: https://www.syslog-ng.com/products/open-source-log-management/3rd-party-binaries.aspx title: [ "syslog-ng Open Source Edition installation packages" ] +sn-blogs: + id: 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/ @@ -142,3 +152,23 @@ lunr-search-help: id: lunr-search-help url: https://lunrjs.com/guides/searching.html title: [ "Lunar search help" ] + +grafana-loki: + id: grafana-loki + url: https://grafana.com/docs/loki/latest/ + title: [ "Grafana Loki" ] + +grafana-loki-endpoint: + id: grafana-loki-endpoint + url: https://grafana.com/docs/loki/latest/reference/loki-http-api/#push-log-entries-to-loki + title: [ "Grafana Loki HTTP endpoint" ] + +app-default-cred: + id: app-default-cred + url: https://cloud.google.com/docs/authentication/application-default-credentials + title: [ "Application Default Credentials" ] + +grpc-core: + id: grpc-core + url: https://grpc.github.io/grpc/core/group__grpc__arg__keys.html + title: [ "GRPC Core library documentation" ] diff --git a/_data/navigation.yml b/_data/navigation.yml index 73a27726..d87aed3b 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -152,6 +152,9 @@ admin-guide-nav: subnav: - title: "wildcard-file() source options" url: /admin-guide/060_Sources/030_Wildcard-file/000_Wildcard-file_options + - title: "Jellyfin" + url: /admin-guide/060_Sources/035_Jellyfin/README + subnav: - title: "kubernetes" url: /admin-guide/060_Sources/040_Kubernetes/README subnav: @@ -384,6 +387,11 @@ admin-guide-nav: subnav: - title: "logmatic() destination options" url: /admin-guide/070_Destinations/120_Logmatic_io/000_Logmatic_options + - title: "Loki" + url: /admin-guide/070_Destinations/125_Loki/README + subnav: + - title: "loki() destination options" + url: /admin-guide/070_Destinations/125_Loki/001_Loki_options - title: "mongodb" url: /admin-guide/070_Destinations/130_MongoDB/README subnav: @@ -1239,4 +1247,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/_includes/doc/admin-guide/manpages-footnote.md b/_includes/doc/admin-guide/manpages-footnote.md index 34d75ba9..5474b5bf 100644 --- a/_includes/doc/admin-guide/manpages-footnote.md +++ b/_includes/doc/admin-guide/manpages-footnote.md @@ -3,11 +3,7 @@ The syslog-ng.conf manual page The syslog-ng manual page ->**NOTE:** For the detailed documentation of syslog-ng OSE see ->[syslog-ng OSE Documentation page](https://www.syslog-ng.com/). -> ->If you experience any problems or need help with syslog-ng OSE, visit ->the [syslog-ng mailing list](https://lists.balabit.hu/mailman/listinfo/syslog-ng). -> ->For news and notifications about syslog-ng OSE, visit the [syslog-ng blogs](https://syslog-ng.com/blog/). +>**NOTE:** +>If you experience any problems or need help with syslog-ng OSE, visit the syslog-ng mailing list. \ +>For news and notifications about syslog-ng OSE, visit the syslog-ng blogs. {: .notice--info} diff --git a/_includes/doc/admin-guide/options/channel-args.md b/_includes/doc/admin-guide/options/channel-args.md new file mode 100644 index 00000000..52cc08ec --- /dev/null +++ b/_includes/doc/admin-guide/options/channel-args.md @@ -0,0 +1,15 @@ +## channel-args() + +| Type:| | +|Default:| | + +*Description:* The `channel-args()` option is available in gRPC-based drivers. The option accepts name-value pairs and sets channel arguments defined in the GRPC Core library documentation. + +### Example: channel-args() declaration + +```config + channel-args( + "grpc.loadreporting" => 1 + "grpc.minimal_stack" => 0 + ) +``` diff --git a/_includes/doc/admin-guide/options/gRPC-keep-alive.md b/_includes/doc/admin-guide/options/gRPC-keep-alive.md new file mode 100644 index 00000000..97cbdea9 --- /dev/null +++ b/_includes/doc/admin-guide/options/gRPC-keep-alive.md @@ -0,0 +1,24 @@ +## keep-alive() + +This option configures the forwarding of [gRPC keepalive pings](https://grpc.io/docs/guides/keepalive/) in syslog-ng OSE. + +### max-pings-without-data() + +| Type:| integer| +|Default:| | + +*Description:* This option definies the maximum number of gRPC pings that are allowed to be sent when there is no data/header frame. Any pings succeeding this limit are not sent. Setting this option to `0` disables this restriction and keep sending pings. + +### time() + +| Type:| number[milliseconds]| +|Default:| | + +*Description:* syslog-ng OSE sends a gRPC keepalive ping after the amount of time defined in the `time()` option elapsed. + +### timeout() + +| Type:| number[milliseconds]| +|Default:| 10| + +*Description:* The time syslog-ng OSE waits for an acknowledgement. \ No newline at end of file diff --git a/_js/custom/navigation.js b/_js/custom/navigation.js index cbaba3af..2dc63f19 100644 --- a/_js/custom/navigation.js +++ b/_js/custom/navigation.js @@ -24,12 +24,12 @@ $(function () { var tocMenuElement = tocElement.querySelector('.toc__menu'); if (null == tocMenuElement || false == tocMenuElement.hasChildNodes) shouldHide = true; - } - if (shouldHide) { - // TOC is autogenerated via 'include toc.html' so its size is not known prior the call of toc.html - // Signal emptiness, css will hide if needed based on it and config settings - // NOTE: Not hiding directly here to behave the same way like the left sidebar does - tocElement.classList.add('empty'); + if (shouldHide) { + // TOC is autogenerated via 'include toc.html' so its size is not known prior the call of toc.html + // Signal emptiness, css will hide if needed based on it and config settings + // NOTE: Not hiding directly here to behave the same way like the left sidebar does + tocElement.classList.add('empty'); + } } } @@ -298,7 +298,7 @@ $(function () { // Add anchors for headings // ------------- function addPageAnchors() { - // FIXME: This magic 6 must be maintained together now with generate_links.rb (and other places ?!) + // FIXME: This magic 6 must be maintained together now with generate_links.rb (and other places ?!), eliminate it! $('.page__content').find('h1, h2, h3, h4, h5, h6').each(function () { var id = $(this).attr('id'); if (id) { @@ -312,21 +312,37 @@ $(function () { }); } - function alterPageForTooltip(content, fullPageContent) { + // To support page links even better if possible in case the page has no description / subtitle, but has some text + // right after the title and before the first heading is presented, it will be treated as the description and will be handled here. + // This part should also handle the case when only the title presented. (a.k.a. not showing the tooltip in that case), + // also responsible to create a uniform look and fell both for page title tooltips and other link tooltips. + // + function alterContentForTooltip(content, url, isFullPageContent) { let tempContainer = document.createElement('div'); tempContainer.innerHTML = content; - if (fullPageContent) - hideTocIfNotNeeded(tempContainer, true); + hideTocIfNotNeeded(tempContainer, true); // Remove/Override some default title style formatting to look better in the tooltip - const pageTitle = tempContainer.querySelector('#page-title'); - if (pageTitle) - pageTitle.style.marginTop = '1em'; - - const pageSubtitle = tempContainer.querySelector('#page-subtitle'); - if (pageSubtitle) - pageSubtitle.style.borderBottom = '0px'; + var pageTitle = tempContainer.querySelector('#page-title'); + if (pageTitle == null) { + // If there is no page title, replace the first heading with an item looks and behaves like the page title + // to have similar result both for page title tooltips and other link item tooltips + // FIXME: This magic 6 must be maintained together now with generate_links.rb (and other places ?!), eliminate it! + var firstHeading = tempContainer.querySelector("h2, h3, h4, h5, h6"); + if (firstHeading) { + // Everything bellow must exist, so intentionally there's no error handling, let it rise + pageTitle = document.querySelector('#page-title').cloneNode(true); + pageTitle.id = firstHeading.id; + + const anchorElement = pageTitle.querySelector("a"); + anchorElement.textContent = firstHeading.textContent; + anchorElement.href = url; + + tempContainer.replaceChild(pageTitle, firstHeading); + } + } + pageTitle.style.marginTop = '1em'; var newContent = tempContainer.innerHTML // remove unnecessary, reqursive inner content tooltips @@ -350,22 +366,37 @@ $(function () { newContent => { var startHeading = newContent.querySelector('#' + startHeadingId); if (startHeading) { - var content = startHeading.outerHTML; // Include the starting element itself + var content = ''; + var heading = startHeading.outerHTML; // Include the starting element itself var nextSibling = startHeading.nextElementSibling; - // Collect all siblings until the next heading or the end of the document - // FIXME: This magic 6 must be maintained together now with generate_links.rb (and other places ?!) + // If handling a page title it will not have next sibling normally at all (we are removed and handling differently the description from the generated page) + // In that case the description is all the normal texts parts in the content, from the top (right bellow the title) to the first heading , try to get, it if there's any. + // If not presented, drop the whole content, return an empty one (a.k.a. do not show title only tooltips) + if (nextSibling == null && false == hasAnchor) { + startHeading = newContent.querySelector('.page__content'); + nextSibling = startHeading.firstElementChild; + // First element is the TOC, skip it to be able to produce an empty content + if (nextSibling && nextSibling.classList.contains('sidebar__right')) + nextSibling = nextSibling.nextElementSibling; + } + // Collect all siblings until the next heading or the end of the initial content + // FIXME: This magic 6 must be maintained together now with generate_links.rb (and other places ?!), eliminate it! while (nextSibling && nextSibling.tagName !== 'H1' && nextSibling.tagName !== 'H2' && nextSibling.tagName !== 'H3' && nextSibling.tagName !== 'H4' && nextSibling.tagName !== 'H5' && nextSibling.tagName !== 'H6') { content += nextSibling.outerHTML; nextSibling = nextSibling.nextElementSibling; } + + if (content.length != 0 || hasAnchor) + content = heading + content; + onSuccess(content); } else - console.error('Start heading not found by ID: ' + startHeadingId); + onError('Start heading not found by ID: ' + startHeadingId); }, error => { - error(error); + onError(error); } ); } @@ -402,10 +433,10 @@ $(function () { tooltip.style.setProperty(posName, newPosition); } - function showTooltip(event, tooltipText, fullPageContent) { + function showTooltip(event, tooltipText, isFullPageContent) { tooltip.innerHTML = tooltipText.innerHTML; - if (fullPageContent) + if (isFullPageContent) tooltip.classList.add("full-content-tooltip"); else tooltip.classList.remove("full-content-tooltip"); @@ -470,7 +501,7 @@ $(function () { element.appendChild(tooltipText); element.addEventListener('mouseover', function (event) { - var fullPageContent = element.classList.contains('full-content-tooltip'); + var isFullPageContent = element.classList.contains('full-content-tooltip'); tooltipTarget = element; @@ -481,18 +512,28 @@ $(function () { function onSuccess(newContent) { if (typeof (newContent) === 'object' && 'innerHTML' in newContent) newContent = newContent.innerHTML; - newContent = alterPageForTooltip(newContent, fullPageContent); - - // cache for reuse - tooltipText.innerHTML = newContent; - showTooltip(event, tooltipText, fullPageContent); + newContent = alterContentForTooltip(newContent, url. isFullPageContent); + + if (newContent.length > 0) { + // cache for reuse + tooltipText.innerHTML = newContent; + showTooltip(event, tooltipText, isFullPageContent); + } + else { + // Quick navigation from another link with tooltip to this link would keep alive the previous tooltip + // force close it, as we don't have tooltip for the current and this is the live hovered one. + hideTooltip(false); + } } function onError(error) { + // Quick navigation from another link with tooltip to this failing link would keep alive the previous tooltip + // force close it, as we don't have tooltip for the current and this is the live hovered one. + hideTooltip(false); console.error('Error loading the tooltip content!' + error); } - if (fullPageContent) { + if (isFullPageContent) { loadContentFromUrl(url, newContent => onSuccess(newContent), error => onError(error)); } else { @@ -500,7 +541,7 @@ $(function () { } } else - showTooltip(event, tooltipText, fullPageContent); + showTooltip(event, tooltipText, isFullPageContent); }); }); diff --git a/_js/main.min.js b/_js/main.min.js index 74212761..d6e5161f 100644 --- a/_js/main.min.js +++ b/_js/main.min.js @@ -8466,9 +8466,9 @@ $(function() { if (tocElement) { var tocMenuElement = tocElement.querySelector(".toc__menu"); if (null == tocMenuElement || false == tocMenuElement.hasChildNodes) shouldHide = true; - } - if (shouldHide) { - tocElement.classList.add("empty"); + if (shouldHide) { + tocElement.classList.add("empty"); + } } } function adjustSidebars() { @@ -8635,14 +8635,23 @@ $(function() { } }); } - function alterPageForTooltip(content, fullPageContent) { + function alterContentForTooltip(content, url, isFullPageContent) { let tempContainer = document.createElement("div"); tempContainer.innerHTML = content; - if (fullPageContent) hideTocIfNotNeeded(tempContainer, true); - const pageTitle = tempContainer.querySelector("#page-title"); - if (pageTitle) pageTitle.style.marginTop = "1em"; - const pageSubtitle = tempContainer.querySelector("#page-subtitle"); - if (pageSubtitle) pageSubtitle.style.borderBottom = "0px"; + hideTocIfNotNeeded(tempContainer, true); + var pageTitle = tempContainer.querySelector("#page-title"); + if (pageTitle == null) { + var firstHeading = tempContainer.querySelector("h2, h3, h4, h5, h6"); + if (firstHeading) { + pageTitle = document.querySelector("#page-title").cloneNode(true); + pageTitle.id = firstHeading.id; + const anchorElement = pageTitle.querySelector("a"); + anchorElement.textContent = firstHeading.textContent; + anchorElement.href = url; + tempContainer.replaceChild(pageTitle, firstHeading); + } + } + pageTitle.style.marginTop = "1em"; var newContent = tempContainer.innerHTML; newContent = newContent.replace(/\bcontent-tooltip\b/g, ""); return newContent; @@ -8655,16 +8664,23 @@ $(function() { loadContentFromUrl(url, newContent => { var startHeading = newContent.querySelector("#" + startHeadingId); if (startHeading) { - var content = startHeading.outerHTML; + var content = ""; + var heading = startHeading.outerHTML; var nextSibling = startHeading.nextElementSibling; + if (nextSibling == null && false == hasAnchor) { + startHeading = newContent.querySelector(".page__content"); + nextSibling = startHeading.firstElementChild; + if (nextSibling && nextSibling.classList.contains("sidebar__right")) nextSibling = nextSibling.nextElementSibling; + } while (nextSibling && nextSibling.tagName !== "H1" && nextSibling.tagName !== "H2" && nextSibling.tagName !== "H3" && nextSibling.tagName !== "H4" && nextSibling.tagName !== "H5" && nextSibling.tagName !== "H6") { content += nextSibling.outerHTML; nextSibling = nextSibling.nextElementSibling; } + if (content.length != 0 || hasAnchor) content = heading + content; onSuccess(content); - } else console.error("Start heading not found by ID: " + startHeadingId); + } else onError("Start heading not found by ID: " + startHeadingId); }, error => { - error(error); + onError(error); }); } const toolTipArrowSize = 10; @@ -8689,9 +8705,9 @@ $(function() { var newPosition = position + "px"; tooltip.style.setProperty(posName, newPosition); } - function showTooltip(event, tooltipText, fullPageContent) { + function showTooltip(event, tooltipText, isFullPageContent) { tooltip.innerHTML = tooltipText.innerHTML; - if (fullPageContent) tooltip.classList.add("full-content-tooltip"); else tooltip.classList.remove("full-content-tooltip"); + if (isFullPageContent) tooltip.classList.add("full-content-tooltip"); else tooltip.classList.remove("full-content-tooltip"); var tooltipPos = getTooltipPos(event, tooltipTarget); var tooltipArrowLeftShift = 2 * toolTipArrowSize; setArrowPosition("--tooltip-arrow-top", -1 * toolTipArrowSize); @@ -8733,25 +8749,30 @@ $(function() { tooltipText.textContent = ""; element.appendChild(tooltipText); element.addEventListener("mouseover", function(event) { - var fullPageContent = element.classList.contains("full-content-tooltip"); + var isFullPageContent = element.classList.contains("full-content-tooltip"); tooltipTarget = element; if (tooltipText.innerHTML === "") { var url = element.href; function onSuccess(newContent) { if (typeof newContent === "object" && "innerHTML" in newContent) newContent = newContent.innerHTML; - newContent = alterPageForTooltip(newContent, fullPageContent); - tooltipText.innerHTML = newContent; - showTooltip(event, tooltipText, fullPageContent); + newContent = alterContentForTooltip(newContent, url.isFullPageContent); + if (newContent.length > 0) { + tooltipText.innerHTML = newContent; + showTooltip(event, tooltipText, isFullPageContent); + } else { + hideTooltip(false); + } } function onError(error) { + hideTooltip(false); console.error("Error loading the tooltip content!" + error); } - if (fullPageContent) { + if (isFullPageContent) { loadContentFromUrl(url, newContent => onSuccess(newContent), error => onError(error)); } else { loadContentPartFrom(url, newContent => onSuccess(newContent), error => onError(error)); } - } else showTooltip(event, tooltipText, fullPageContent); + } else showTooltip(event, tooltipText, isFullPageContent); }); }); document.addEventListener("mousemove", function(event) { diff --git a/_layouts/single.html b/_layouts/single.html index 26340629..855cff47 100644 --- a/_layouts/single.html +++ b/_layouts/single.html @@ -31,10 +31,16 @@ {% unless page.header.overlay_color or page.header.overlay_image %}
{% if page.title %} -

+ {% comment %}{% endcomment %} +

{% endif %} + {% comment %}{% endcomment %} {% include page__meta.html %}
{% endunless %} diff --git a/_plugins/generate_links.rb b/_plugins/generate_links.rb index 35a7a852..3ab16a8d 100644 --- a/_plugins/generate_links.rb +++ b/_plugins/generate_links.rb @@ -21,7 +21,6 @@ def write_yaml_file(file_path, data) file.write("id: " + data["id"] + "\n") file.write("url: " + data["url"] + "\n") file.write("title: " + data["title"] + "\n") - file.write("description: " + data["description"] + "\n") end #puts file_path end @@ -65,14 +64,11 @@ def generate_links(page, ids, titles) # links must be used via the markdown_link include (or with the '| relative_url' filter) that will handle this page_url = page.url.sub(/\.[^.]+$/, "") # page.url.sub(/^\//, "").sub(/\.[^.]+$/, "") page_path = page.destination("").split("_site/").last # Get the path to the generated HTML file - page_description = page['subtitle']&.strip - page_description = page_description ? page_description : page['description']&.strip - page_description = page_description ? page_description : "" - #puts "page_id: " + page_id + "\npage_url :" + page_url + "\npage_path: " + page_path + "\npage_description: " + page_description + #puts "page_id: " + page_id + "\npage_url :" + page_url + "\npage_path: " + page_path # Find all heading elements (now from h1 to h6) - # NOTE: This will not contain the

page title, as that is out of the page.content # FIXME: This magic 6 must be maintained together now with navigation.js (and other places?!) + # NOTE: This will not contain the

page title, as that is out of the page.content (1..6).each do |level| headings = doc.css("h#{level}") @@ -86,7 +82,6 @@ def generate_links(page, ids, titles) "id" => page_id + "##{heading_id}", "url" => page_url + "##{heading_id}", "title" => '"' + heading.text + '"', - "description" => '""' } #register_id(page, link_data["id"], link_data["title"], ids, titles) @@ -97,8 +92,8 @@ def generate_links(page, ids, titles) end # Enumerate all named anchor elements too - # This way we can referenve not automatically created links via our - # [[title|id]] or {# include markdown_link ...$} extensions + # This way we can reference not automatically created links via our + # [[title|id]] or {% include markdown_link ... %} extensions as well doc.xpath('//a[@name]').each do |anchor| anchor_name = anchor['name'] anchor_text = anchor.text @@ -110,7 +105,6 @@ def generate_links(page, ids, titles) "id" => anchor_id, "url" => page_url + "##{anchor_name}", "title" => '"' + (anchor_text.empty? ? anchor_id : anchor_text) + '"', - "description" => '""' } #register_id(page, link_data["id"], link_data["title"], ids, titles) @@ -119,13 +113,12 @@ def generate_links(page, ids, titles) write_yaml_file(file_path, link_data) end - # Create links data for the page + # Create links data for the page itself too page_title = page.data["title"] page_link_data = { "id" => page_id, "url" => page_url, "title" => '"' + page_title + '"', - "description" => '"' + page_description + '"' } register_id(page, page_link_data["id"], page_link_data["title"], ids, titles) diff --git a/_plugins/generate_tooltips.rb b/_plugins/generate_tooltips.rb index 431c7247..0cec41ef 100644 --- a/_plugins/generate_tooltips.rb +++ b/_plugins/generate_tooltips.rb @@ -47,7 +47,7 @@ def prefixed_url(url, base_url) return url end - def make_tooltip(page, page_links, id, url, needs_tooltip, match) + def make_tooltip(page, page_links, id, url, match) match_parts = match.split(/\|/) # If the text has an '|' it means it comes from our special autolink/tooltip [[text|id]] markdown block # We have to reparse it a bit and get the id we must use @@ -64,13 +64,13 @@ def make_tooltip(page, page_links, id, url, needs_tooltip, match) # 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 + '' + replacement_text = '' + match + '' puts "replacement_text: " + replacement_text return replacement_text end - def process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, needs_tooltip, add_separator) + def process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, add_separator) markdown_part = markdown_part.gsub(full_pattern) do |match| left_separator = $1 @@ -78,7 +78,7 @@ def process_markdown_part(page, markdown_part, page_links, full_pattern, id, url right_separator = $3 #puts "\nmatch: #{match}\nleft_separator: #{left_separator}\nmatched_text: #{matched_text}\nright_separator: #{right_separator}" - replacement_text = make_tooltip(page, page_links, id, url, needs_tooltip, matched_text) + replacement_text = make_tooltip(page, page_links, id, url, matched_text) if add_separator replacement_text = left_separator + replacement_text + right_separator end @@ -112,7 +112,6 @@ def process_markdown_parts(page, markdown) # id = link_data["id"] these must match too title = page_titles_data["title"] # link_data["title"] is an array of titles that all must be already in the page_links_ids_sorted_by_title array url = prefixed_url(link_data["url"], base_url) - needs_tooltip = (link_data["description"] || has_anchor?(url)) #puts "searching for #{title}" pattern = Regexp.escape(title) @@ -126,14 +125,14 @@ def process_markdown_parts(page, markdown) # 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! - full_pattern = /(^|[\s.,;:&'"\-(])(#{pattern})([\s.,;:&'"\-)]|\z)(?![^<]*?<\/a>)/ - markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, needs_tooltip, true) + 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 # Handle own auto tooltip links [[ ]], [[ | ]], [[ |id ]] full_pattern = /(\[\[)(#{pattern}|#{pattern}\|.+|.*\|#{id})(\]\])/ - markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, needs_tooltip, false) + markdown_part = process_markdown_part(page, markdown_part, page_links, full_pattern, id, url, false) end end @@ -232,7 +231,11 @@ def page_links_ids_sorted_by_title(page_links) end end - sorted_arr.sort_by { |page| page["title"].downcase }.reverse + # With this reversed length sort order we try to guarantie that + # the autolink/tooltip title pattern matching finds titles like + # 'Soft macros' before 'macros' + # In most of the cases matching the longer titles first will eliminate such issues + sorted_arr.sort_by { |page| page["title"].length }.reverse end def gen_page_link_data(links_dir, link_files_pattern) @@ -251,10 +254,7 @@ def gen_page_link_data(links_dir, link_files_pattern) page_id = yaml_content['id'] page_url = yaml_content['url'] page_title = yaml_content['title'] - page_description = yaml_content['description'] chars_to_remove = %{"'} #!?.:;} - page_description = page_description.gsub(/\A[#{Regexp.escape(chars_to_remove)}]+|[#{Regexp.escape(chars_to_remove)}]+\z/, '') - #puts "page_description: " + page_description page_title = page_title.gsub(/\A[#{Regexp.escape(chars_to_remove)}]+|[#{Regexp.escape(chars_to_remove)}]+\z/, '') #puts "page_title: " + page_title if page_title.length == 0 @@ -270,7 +270,6 @@ def gen_page_link_data(links_dir, link_files_pattern) "id" => page_id, "url" => page_url, "title" => [ page_title ], - "description" => (page_description.length > 0 ? true : false) } # Add the page_link_data object to the ID dictionary @@ -287,16 +286,15 @@ def gen_page_link_data(links_dir, link_files_pattern) puts "Unknow ID (#{alias_id}) in alias definition" exit 4 end - _, aliases = alias_data.first - page_link_data["title"] = aliases.concat(page_link_data["title"]) - #puts "page_link_data: #{page_link_data}" + page_link_data["title"].concat(alias_data["aliases"]) + # puts "page_link_data: #{page_link_data}" end # Just for debugging # pp page_links_dictionary - page_links_ids_sorted_by_title(page_links_dictionary).each do |data| - #puts data - end + # page_links_ids_sorted_by_title(page_links_dictionary).each do |data| + # puts data + # end #pp page_links_dictionary return page_links_dictionary @@ -351,7 +349,11 @@ def JekyllTooltipGen_debug_filter_pages?(page) return debug_ok end -def JekyllTooltipGen_hack_description_in(page_has_subtitle, page_has_description, page, desc_hack_separator) +# Description/Subtitle rendering happens separately in Jekyll by default +# We can force this way is being rendered with the content, the same way like the normal content +# NOTE: To get this work we had to modify the Minimal Mistakes default single.thml too, see there. +# +def JekyllTooltipGen_hack_description_in(page_has_subtitle, page_has_description, page) description = nil if page_has_subtitle description = page.data["subtitle"] @@ -362,34 +364,8 @@ def JekyllTooltipGen_hack_description_in(page_has_subtitle, page_has_description #puts "description: #{description}" end end - if page_has_description || page_has_subtitle - # NOTE: Additional line breaks are essential here otherwise special constructs like tables, liquid notice or code block, etc. might break - # Added double \n\n just to be prepared for the case if there's no \n at all at the file ending - page.content = page.content + "\n\n" + desc_hack_separator + description - end -end - -def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_description, page, desc_hack_separator) - description = nil - - content_parts = page.content.split(desc_hack_separator) - content_parts.each_with_index do |content_part, content_part_index| - #puts "---------------\ncontent_part_index: " + content_part_index.to_s + "\ncontent_part: " + content_part - if content_part_index.even? - page.content = content_part - else - description = content_part - end - end - - if page_has_subtitle - page.data["subtitle"] = description - #puts "subtitle: #{description}" - else - if page_has_description - page.data["description"] = description - #puts "description: #{description}" - end + if description + page.content = description + "\n" + page.content end end @@ -399,7 +375,6 @@ def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_descriptio # - https://jekyllrb.com/docs/plugins/hooks/ # - https://github.com/jekyll/jekyll/blob/12ab35011f6e86d49c7781514f9dd1d92e43ea11/features/hooks.feature#L37 # -JekyllTooltipGen_desc_hack_separator = '

%%%description-separator-DO-NOT-REMOVE%%%

' JekyllTooltipGen_links_folder = '_data/links' JekyllTooltipGen_navigation_yaml = '_data/navigation.yml' JekyllTooltipGen_link_aliases_yaml = '_data/link_aliases.yml' @@ -418,6 +393,7 @@ def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_descriptio # This is used now to # - set the page nav_ndx correctly to support our custom bottom collection elements navigator # - set additional page data elements that will be used during all the passes +# - add the description to the beginning of the page.content to get it rendred correclty the same way, together with the page content # # NOTE: Do not use this site based enumeration directly for the page content manipulation as well # as that needs proper per-page payload data (or TODO: figure out how to get it in that case properly) @@ -453,6 +429,12 @@ def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_descriptio page.data["page_links"] = $JekyllTooltipGen_page_links page.data["page_links_ids_sorted_by_title"] = $JekyllTooltipGen_page_links_ids_sorted_by_title # puts "collection: " + (page.respond_to?(:collection) ? page.collection.label : "") + ", nav_ndx: " + (link_data != nil ? link_data['nav_ndx'].to_s : "") + ", page_url: #{page_url}, page: #{page.relative_path}" + + page_has_subtitle = (page.data["subtitle"] && false == page.data["subtitle"].empty?) + page_has_description = (page.data["description"] && false == page.data["description"].empty?) + if page_has_description || page_has_subtitle + JekyllTooltipGen_hack_description_in(page_has_subtitle, page_has_description, page) + end end end end @@ -460,7 +442,6 @@ def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_descriptio # 2nd pass # # This is used now to -# - add the description to the page end to get it rendred correclty the same way, together with the page content (will be removed/handled in the 3rd pass) # - render the page content manually and create the autolinks and tooltips # Jekyll::Hooks.register [:pages, :documents], :pre_render do |page, payload| @@ -470,10 +451,6 @@ def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_descriptio site = page.site - page_has_subtitle = (page.data["subtitle"] && false == page.data["subtitle"].empty?) - page_has_description = (page.data["description"] && false == page.data["description"].empty?) - JekyllTooltipGen_hack_description_in(page_has_subtitle, page_has_description, page, JekyllTooltipGen_desc_hack_separator) - # create a template object template = site.liquid_renderer.file(page.path).parse(page.content) liquid_options = site.config["liquid"] @@ -487,18 +464,3 @@ def JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_descriptio Jekyll::TooltipGen.generate_tooltips(page, $JekyllTooltipGen_should_build_persistent_tooltips) end - -# 3rd pass -# -# This is used now to -# - remove the added hackish description block from the page end and replace the description with the now correctly rendered one -# -Jekyll::Hooks.register [:pages, :documents], :post_convert do |page| - next if false == $JekyllTooltipGen_should_build_tooltips - next if false == $JekyllTooltipGen_markdown_extensions.include?(File.extname(page.relative_path)) && File.extname(page.relative_path) != ".html" - next if false == JekyllTooltipGen_debug_filter_pages?(page) - - page_has_subtitle = (page.data["subtitle"] && false == page.data["subtitle"].empty?) - page_has_description = (page.data["description"] && false == page.data["description"].empty?) - JekyllTooltipGen_hack_description_out(page_has_subtitle, page_has_description, page, JekyllTooltipGen_desc_hack_separator) -end 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/_admin-guide/030_Installing_syslog-ng/000_Compiling_syslog-ng_from_source.md b/doc/_admin-guide/030_Installing_syslog-ng/000_Compiling_syslog-ng_from_source.md index 965df8bf..d600c2bb 100644 --- a/doc/_admin-guide/030_Installing_syslog-ng/000_Compiling_syslog-ng_from_source.md +++ b/doc/_admin-guide/030_Installing_syslog-ng/000_Compiling_syslog-ng_from_source.md @@ -8,7 +8,7 @@ description: >- --- For a list of third-party packages available for various Linux, UNIX, -and other platforms, see [syslog-ng Open Source Edition installation packages](https://www.syslog-ng.com/products/open-source-log-management/3rd-party-binaries.aspx). +and other platforms, see syslog-ng Open Source Edition installation packages. ## Steps diff --git a/doc/_admin-guide/030_Installing_syslog-ng/README.md b/doc/_admin-guide/030_Installing_syslog-ng/README.md index ca641056..bb735745 100644 --- a/doc/_admin-guide/030_Installing_syslog-ng/README.md +++ b/doc/_admin-guide/030_Installing_syslog-ng/README.md @@ -9,8 +9,7 @@ description: >- - You can install syslog-ng OSE on many platforms using the package manager and official repositories of the platform. For a list of third-party packages available for various Linux, UNIX, and other - platforms, see [syslog-ng Open Source Edition installation - packages](https://www.syslog-ng.com/products/open-source-log-management/3rd-party-binaries.aspx). + platforms, see syslog-ng Open Source Edition installation packages. - For instructions on compiling syslog-ng Open Source Edition from the source code, see Compiling syslog-ng from source diff --git a/doc/_admin-guide/060_Sources/035_Jellyfin/README.md b/doc/_admin-guide/060_Sources/035_Jellyfin/README.md new file mode 100644 index 00000000..e281dbd3 --- /dev/null +++ b/doc/_admin-guide/060_Sources/035_Jellyfin/README.md @@ -0,0 +1,26 @@ +--- +title: Jellyfin log source +short_title: Jellyfin +id: adm-src-jfin +description: >- + In syslog-ng OSE 4.7 and later versions it is possible to use the `jellyfin()` source to read [Jellyfin](https://jellyfin.org/) logs from its log file output. +--- + +### Example: minimal configuration of jellyfin() + +```config +source s_jellyfin { + jellyfin( + base-dir("/path/to/jellyfin/root/log/dir") + filename-pattern("log_*.log") + ); +}; +``` + +The `jellyfin()` source can use wildcard-file() source options, since it is based on the `wildcard-file()` source. + +The `jellyfin()` driver is a reusable configuration snippet. For more information on using configuration snippets, see Reusing configuration blocks. The source of this configuration snippet can be accessed as the Jellyfish config file on GitHub. [GitHub](https://github.com/syslog-ng/syslog-ng/blob/master/scl/jellyfin/jellyfin.conf). + +For more information about Jellyfin logs, see the Jellyfin Main Configuration and Jellyfin Log Directory section in the Jellyfin documentation. +* [https://jellyfin.org/docs/general/administration/configuration/#main-configuration](https://jellyfin.org/docs/general/administration/configuration/#main-configuration) +* [https://jellyfin.org/docs/general/administration/configuration/#log-directory](https://jellyfin.org/docs/general/administration/configuration/#log-directory) \ No newline at end of file diff --git a/doc/_admin-guide/070_Destinations/125_Loki/001_Loki_options.md b/doc/_admin-guide/070_Destinations/125_Loki/001_Loki_options.md new file mode 100644 index 00000000..57c26dd4 --- /dev/null +++ b/doc/_admin-guide/070_Destinations/125_Loki/001_Loki_options.md @@ -0,0 +1,136 @@ +--- +title: loki() destination options +id: adm-dest-loki-opt +--- + +The `loki()` driver sends messages to a Loki Grafana database and has the following options: + +## auth() + +The `auth()` option can be used to set the authentication of the driver. The default state of this option is `insecure`, as it is not defined. + +The following sub-options are available for `auth()`. + +### adc() + +This option is an authentication method that is only available for destinations. For more information, see Application Default Credentials. + +### alts() + +This option is an accessible authentication available for Google infrastructures. Service accounts can be listed with the nested `target-service-account()` option, to match these against the server. + +#### Example: configure a Loki destination using auth(alts()) + +```config +destination { + loki( + port(1234) + auth(alts()) + ); + }; +``` + +### insecure() + +This option can be used to disable authentication: `auth(insecure())`. + +### tls() + +The `tls()` option accepts the following nested sub-options. +* ca-file() +* key-file() +* cert-file() + +#### Example: configure a Loki destination using auth(tls()) + +```config +destination { + loki( + url("loki-server:123") + auth( + tls( + ca-file("/path/to/ca.pem") + key-file("/path/to/key.pem") + cert-file("/path/to/cert.pem") + ) + ) + ); + }; +``` + +{% include doc/admin-guide/options/batch-bytes.md %} + +{% include doc/admin-guide/options/batch-lines.md %} + +{% include doc/admin-guide/options/batch-timeout.md %} + +{% include doc/admin-guide/options/channel-args.md %} + +{% include doc/admin-guide/options/gRPC-keep-alive.md %} + +## labels() + +This option defines the labels applied to the message as they are sent to the destination. + +**Declaration:** + +```config +labels( + "label-output-name" => "field-of-the-message" +) +``` + +## template() + +| Type:| template or template-function| +|Default:| ${ISODATE} ${HOST} ${MSGHDR} ${MSG}| + +*Description:* This option specifies a template that defines the logformat to be used in the destination. For more information on macros and template functions, see Macros of syslog-ng OSE and Template functions of syslog-ng OSE. + +## tenant-id() + +| Type:| string| +|Default:| | + +Available in syslog-ng OSE 4.7 and later versions. + +*Description:* This option sets the tenant ID for multi-tenant cases. + +**Declaration:** + +```config +loki( + url("localhost:9096") + labels( + "app" => "$PROGRAM", + "host" => "$HOST", + ) + + tenant-id("testTenant") +); +``` + +## timestamp() + +| Type:| `current`, `received`, `msg`| +|Default:| `current`| + +*Description:* This option sets the timestamp type to be used for messages sent to a Loki destination. + +**NOTE:** Loki destinations only accept subsequent messages with increasing timestamps. Messages with timestamps deviating from this are rejected. +{: .notice--info} + +The timestamp types are the following. + +* `current`: The message procession output timestamp is used. This type guarantees an increasing timestamp order, but can deviate significantly from the message generation time. +* `msg`: The original timestamp of the message is used. +* `received`: The timestamp of message reception is used. + +## url() + +| Type:| string| +|Default:| localhost:9095| + +*Description:* This option specifies the URL of the Loki endpoint. + +{% include doc/admin-guide/options/workers.md %} diff --git a/doc/_admin-guide/070_Destinations/125_Loki/README.md b/doc/_admin-guide/070_Destinations/125_Loki/README.md new file mode 100644 index 00000000..13880d80 --- /dev/null +++ b/doc/_admin-guide/070_Destinations/125_Loki/README.md @@ -0,0 +1,25 @@ +--- +title: 'loki(): Storing messages in a Grafana Loki database' +short_title: Loki +id: adm-dest-loki +description: >- + In syslog-ng OSE 4.4 and later versions the `loki()` destination can be used to send log data to Grafana Loki. + + For more information on the message format, see Grafna Loki HTTP endpoint. +--- + +### Example: loki() destination configuration + +```config +loki( + url("localhost:9096") + labels( + "app" => "$PROGRAM", + "host" => "$HOST", + ) + + workers(16) + batch-timeout(10000) + batch-lines(1000) +); +``` diff --git a/doc/_admin-guide/120_Parser/014_panos_parser/README.md b/doc/_admin-guide/120_Parser/014_panos_parser/README.md index f759717e..7a290b13 100644 --- a/doc/_admin-guide/120_Parser/014_panos_parser/README.md +++ b/doc/_admin-guide/120_Parser/014_panos_parser/README.md @@ -23,9 +23,7 @@ Structuring macros, metadata, and other value-pairs. - Version 3.29 of syslog-ng OSE or later. **NOTE:** Most Linux distributions feature syslog-ng OSE versions - earlier than version 3.29. For up-to-date binaries, visit [the - syslog-ng third-party binaries - page](https://www.syslog-ng.com/products/open-source-log-management/3rd-party-binaries.aspx). + earlier than version 3.29. For up-to-date binaries, visit the syslog-ng Open Source Edition installation packages page. {: .notice--info} - PAN-OS log messages from Palo Alto Networks devices. diff --git a/doc/_admin-guide/120_Parser/023_db_parser/001_Using_pattern_databases/001_Downloading_sample_patterndb.md b/doc/_admin-guide/120_Parser/023_db_parser/001_Using_pattern_databases/001_Downloading_sample_patterndb.md index e35fcd58..527a0eae 100644 --- a/doc/_admin-guide/120_Parser/023_db_parser/001_Using_pattern_databases/001_Downloading_sample_patterndb.md +++ b/doc/_admin-guide/120_Parser/023_db_parser/001_Using_pattern_databases/001_Downloading_sample_patterndb.md @@ -33,5 +33,5 @@ For legal details, the full text of the license is [available here](https://crea If you create patterns that are not available in the GitHub repository, consider sharing them with us and the syslog-ng community. To do this, -open a GitHub issue, or send them to the [syslog-ng mailing -list](https://lists.balabit.hu/mailman/listinfo/syslog-ng/). +open a GitHub issue, or send them to the syslog-ng mailing +list. diff --git a/doc/_admin-guide/170_Troubleshooting_syslog-ng/README.md b/doc/_admin-guide/170_Troubleshooting_syslog-ng/README.md index 57f36ed9..a7c57eef 100644 --- a/doc/_admin-guide/170_Troubleshooting_syslog-ng/README.md +++ b/doc/_admin-guide/170_Troubleshooting_syslog-ng/README.md @@ -50,9 +50,9 @@ description: >- Things to consider when forwarding messages between syslog-ng OSE hosts. - In case you experience a problem that is not covered in this guide, - send it to our [mailing list](https://lists.balabit.hu/mailman/listinfo/syslog-ng/). + send it the syslog-ng mailing list. - To report bugs found in syslog-ng OSE, [visit our GitHub issues page](https://github.com/syslog-ng/syslog-ng/issues/). + To report bugs found in syslog-ng OSE, visit the syslog-ng issue tracker on GitHub. Precompiled binary packages are available for free from various - third-parties. See [the list of precompiled syslog-ng OSE binary packages](https://www.syslog-ng.com/products/open-source-log-management/3rd-party-binaries.aspx). + third-parties. See the list of precompiled syslog-ng OSE binary packages. 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/_dev-guide/chapter_4/section_2/README.md b/doc/_dev-guide/chapter_4/section_2/README.md index de78ee6d..bf16f3d0 100644 --- a/doc/_dev-guide/chapter_4/section_2/README.md +++ b/doc/_dev-guide/chapter_4/section_2/README.md @@ -20,7 +20,7 @@ Like every project syslog-ng also uses different libraries and build-systems tha ### Dependencies -1. [[Install Homebrew|dev-inst-macos#Homebrew]] on your system. +1. [[Install Homebrew|dev-inst-macos#homebrew]] on your system. **Hint:** Don't forget to set up the homebrew environment, follow the instructions in your terminal! [[Here|homebrew-inst-detailed]] you can find an even more detailed instruction about the topic. {: .notice--info} 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 diff --git a/doc/site-internal/lunr_search_help.md b/doc/site-internal/lunr_search_help.md index 865c5f30..cfc95c2f 100644 --- a/doc/site-internal/lunr_search_help.md +++ b/doc/site-internal/lunr_search_help.md @@ -13,7 +13,7 @@ Please visit the original Lunar site for more information. The simplest way to start is to pass the text on which you want to search into the search field: ``` javascript -'foo' +foo ``` The above will return details of all documents that match the term “foo”. Although it looks like a string, the search method parses the string into a search query. This supports special syntax for defining more complex queries. @@ -21,7 +21,7 @@ The above will return details of all documents that match the term “foo”. Al Searches for multiple terms are also supported. If a document matches at least one of the search terms, it will show in the results. The search terms are combined with OR. ``` javascript -'foo bar' +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. @@ -37,13 +37,13 @@ For example, let’s say you’re indexing a collection of documents about JavaS 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”: ``` javascript -'foo*' +foo* ``` This will match all documents that end with ‘oo’: ``` javascript -'*oo' +*oo ``` Leading wildcards, as in the above example, should be used sparingly. They can have a negative impact on the performance of a search, especially in large indexes. @@ -51,7 +51,7 @@ Leading wildcards, as in the above example, should be used sparingly. They can h Finally, a wildcard can be in the middle of a term. The following will match any documents that contain a term that begins with “f” and ends in “o”: ``` javascript -'f*o' +f*o ``` It is also worth noting that, when a search term contains a wildcard, no stemming is performed on the search term. @@ -65,13 +65,13 @@ To indicate that a term must be present in matching documents the term should be The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: ``` javascript -'+foo bar -baz' ++foo bar -baz ``` To simulate a logical AND search of “foo AND bar” mark both terms as required: ``` javascript -'+foo +bar' ++foo +bar ``` ## Fields @@ -79,7 +79,7 @@ To simulate a logical AND search of “foo AND bar” mark both terms as require By default, Lunr will search all fields in a document for the query term, and it is possible to restrict a term to a specific field. The following example searches for the term “foo” in the field title: ``` javascript -'title:foo' +title:foo ``` The search term is prefixed with the name of the field, followed by a colon (:). The field must be one of the fields defined when building the index. Unrecognised fields will lead to an error. @@ -87,7 +87,7 @@ The search term is prefixed with the name of the field, followed by a colon (:). Field-based searches can be combined with all other term modifiers and wildcards, as well as other terms. For example, to search for words beginning with “foo” in the title or with “bar” in any field the following query can be used: ``` javascript -'title:foo* bar' +title:foo* bar ``` ## Boosts @@ -95,13 +95,13 @@ Field-based searches can be combined with all other term modifiers and wildcards In multi-term searches, a single term may be important than others. For these cases Lunr supports term level boosts. Any document that matches a boosted term will get a higher relevance score, and appear higher up in the results. A boost is applied by appending a caret (^) and then a positive integer to a term. ``` javascript -'foo^10 bar' +foo^10 bar ``` The above example weights the term “foo” 10 times higher than the term “bar”. The boost value can be any positive integer, and different terms can have different boosts: ``` javascript -'foo^10 bar^5 baz' +foo^10 bar^5 baz ``` ## Fuzzy Matches @@ -109,7 +109,7 @@ The above example weights the term “foo” 10 times higher than the term “ba Lunr supports fuzzy matching search terms in documents, which can be helpful if the spelling of a term is unclear, or to increase the number of search results that are returned. The amount of fuzziness to allow when searching can also be controlled. Fuzziness is applied by appending a tilde (~) and then a positive integer to a term. The following search matches all documents that have a word within 1 edit distance of “foo”: ``` javascript -'foo~1' +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.