Malware Tools Repository

The sidebar highlights the current page by applying an active class to the list item (<li>) when the page.url matches the item's url attribute.

Important Implementation Details:

1. URL Matching: The url value in your sidebar data file must match the Jekyll {{page.url}} exactly.
2. Permalinks: Because the site uses permalinks to pull topics out of subfolders into the root directory during build, your sidebar url values should not include the project folder path. They should represent the final URL path as it appears in the browser.

If the URLs match, the active class is applied, which also ensures the parent accordion section remains expanded.

# Example sidebar data entry
- title: Understanding how the sidebar works
  url: mydoc_understand_sidebar.html
  output: web, pdf

The search functionality is driven by a search.json file located in the root directory. This file generates a JSON array of page data that a JavaScript client uses to perform keyword matching. The search scans the following fields:

• title
• summary
• keywords
• tags

Note that the search is a simple keyword matcher; it does not provide a dedicated results page or keyword highlighting (bolding), but instead displays a list of matching page titles instantly as you type.

[
{
"title": "search",
"tags": "tags",
"keywords": "keywords",
"url": "url",
"summary": "summary"
}
]

The PDF generation process follows a specific sequence to ensure all links and styles are correctly applied:

1. Jekyll Build: A Jekyll build is triggered using a specialized configuration file (e.g., pdfconfigs/config_mydoc_pdf.yml). This build generates a printer-friendly HTML site.
2. Link List Generation: A file named prince-list.txt is generated. This file iterates through your sidebar YML and creates a list of URLs for every item marked with output: pdf.
3. Prince XML Execution: The Prince command is called using the --input-list flag, pointing to prince-list.txt. Prince reads the list of HTML files, processes them (including JavaScript if --javascript is enabled), and compiles them into a single PDF.

This mechanism ensures that Prince has a continuous stream of pages to process, allowing it to handle page numbering and cross-references accurately.

The or operator allows you to check multiple conditions. When using or, you must specify the full condition for each side of the operator; you cannot shorthand the second condition.

{% if page.audience contains "vegan" or page.audience == "vegetarian" %}
    Then run this...
{% endif %}

When using kramdown-flavored Markdown, you must ensure the first character of every list item aligns symmetrically on the left edge. If the items do not line up, the list will not render correctly.

Alignment Rule:

• For numbers 1 through 9: Use two spaces after the dot.
• For numbers 10 and up: Use one space after the dot.

Lining up the left edge ensures the list stays intact.

The PDF generation process supports running JavaScript functions within CSS using prince-script(). This allows you to inject dynamic data like datestamps or guide names into headers and footers.

1. Define the function in your HTML (e.g., in _includes/head_print.html) using Prince.addScriptFunc:

   Prince.addScriptFunc("datestamp", function() {
       return "PDF last generated: " + new Date().toLocaleDateString();
   });

2. Call the function in CSS:

   @page {
       @top-right {
           content: prince-script(datestamp);
       }
   }

Note: You must include the --javascript flag in your prince CLI command for these functions to work.

<script>
    Prince.addScriptFunc("datestamp", function() {
        return "PDF last generated: {{ site.time | date: '%B %d, %Y' }}";
    });
</script>

In Jekyll, you can separate data from presentation by storing structured data in YAML files (located in the _data folder) and using Liquid templating to inject that data into HTML. This is a common pattern for building dynamic components like Tables of Contents (TOC).

Workflow:

1. Store Data: Define your structure in a .yml file within the _data directory.
2. Access Data: Use Liquid syntax to access the data via site.data.[filename].[key].
3. Render: Use Liquid for loops and conditions to iterate through lists and mappings to generate HTML structure.

<!-- Accessing a file named samplelist.yml -->
{{ site.data.samplelist.some_key }}

Mercurial offers two primary ways to manage development lines:

1. Bookmarks: These are tags that move forward automatically to subsequent changesets. They do not leave a permanent mark on the history. You can switch to a bookmark's state using hg update [bookmark_name].
2. Named Branches: These are indelible marks that are part of the changeset itself. They are pushed and pulled between repositories.

Key differences:

• Bookmarks are essentially moving tags; Named branches are permanent metadata.
• Named branches travel between repositories; Bookmarks do not.
• The default branch name is default.

# Creating and switching between bookmarks
hg bookmark main
hg bookmark feature
hg update feature