### Check Flatmark Version Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/quickstart.md Verify the Flatmark installation by checking its version. This command confirms that Flatmark has been installed correctly. ```shell user$ flatmark --version Flatmark CLI 1.2.3 ``` -------------------------------- ### Extend Base Layout in page.html Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md Sets up the `page.html` layout to extend the base template and define its content block. This example includes placeholder text for custom page-specific content. ```html {% raw %} {{ '{%' }} extends "base.html" %} {{ '{%' }} block content %} {{'{{'}} page.content {{'}}'}} Custom content for the page goes here. {{ '{%' }} endblock %} {% endraw %} ``` -------------------------------- ### Generate GraalVM Native Image Metadata Source: https://github.com/sake92/flatmark/blob/main/DEV.md Run this command to generate GraalVM native image metadata. This is necessary after dependency changes. Interact with the application after starting it to ensure all metadata is captured, then kill the process. ```bash ./mill -i cli.assembly graalvm/java -agentlib:native-image-agent=config-output-dir=cli/resources/META-INF/native-image --sun-misc-unsafe-memory-access=allow -jar out/cli/assembly.dest/out.jar serve -i examples/multilang --no-cache # now play with the app, change files, trigger some actions, etc. # then kill the process and it will generate the metadata ./mill -i cli.nativeImage2 ``` -------------------------------- ### Configuration and Layout Directories Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/files-layout.md Illustrates the structure of configuration files and directories, including site configuration, layouts, includes, translations, themes, and output. ```bash _config.yaml <-- global site config _layouts/ <-- templates ├── base.html <-- base layout extended by other layouts ├── index.html <-- index.md layout └── page.html <-- pages layout _includes/ <-- snippets/fragments/helpers/ ├── header.html <-- header snippet ├── footer.html <-- footer snippet ├── toc.html <-- table of contents snippet └── pagination.html <-- pagination snippet _i18n/ <-- dynamic translations for the site ├── my_translations.properties <-- default language translations └── my_translations_de.properties <-- german translations _themes/ <-- custom local themes └── my_theme/ <-- local theme folder/ ├── _layouts/ <-- local theme layouts └── _includes/ <-- local theme includes _site/ <-- result of rendering, this will be deployed .flatmark-cache <-- cache for the flatmark results, can be deleted ``` -------------------------------- ### Define and Render Custom Tutorials with Jinja Source: https://github.com/sake92/flatmark/blob/main/docs/content/howtos/content.md Use Jinja variables to define a list of tutorials and then loop through them to render custom navigation. This is useful for creating ordered tutorial series that do not rely on default pagination. ```markdown Tutorials: {% raw %} {{ '{%' }} set tutorials = [ { "label": "My tutorial 1", "url": "/tutorials/tutorial1.html" }, { "label": "My tutorial 2", "url": "/tutorials/tutorial2.html" } ] %} {% endraw %} {% raw %} {{ '{%' }} for tut in tutorials %} - [{{ '{{' }} tut.label }}]({{ '{{' }} tut.url }}) {{ '{%' }} endfor %} {% endraw %} ``` -------------------------------- ### Configure Theme in _config.yaml Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/themes.md Specify a theme in your `_config.yaml` file. Use `source` to point to a local folder or a GitHub repository URL. ```yaml theme: source: my_local_theme ``` ```yaml theme: source: https://github.com/my_user/my_repo?branch=main&folder=my_folder ``` -------------------------------- ### Serve Flatmark Site Locally Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/quickstart.md Build and serve your Flatmark site locally. Navigate to your site's root directory in the terminal and run this command. The site will be available at http://localhost:5555. ```shell user$ flatmark serve ``` -------------------------------- ### Global Site Configuration (_config.yaml) Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/configuration.md Defines global settings for the entire Flatmark site, such as website name, description, base URL, theme, search, code highlighting, math highlighting, categories, language, and timezone. The `base_url` can also be set via the `FLATMARK_BASE_URL` environment variable. ```yaml name: My Cool Blog # website name description: My Cool Blog Description # website description base_url: https://mydomain.com/subpath # URL where website will be deployed theme: enabled: true # enable theme source: my_local_theme # website theme search: enabled: true # enable search code_highlight: enabled: true # enable code highlighting math_highlight: enabled: true # enable math highlighting categories: blog: # content/blog/ folder label: Blog docs: # content/docs/ folder label: Documentation lang: en # default language timezone: Europe/Sarajevo ... ``` -------------------------------- ### Basic HTML Structure Source: https://github.com/sake92/flatmark/blob/main/examples/simple/content/index.md Demonstrates a standard HTML document structure. ```html Page Title

This is a Heading

This is a paragraph.

``` -------------------------------- ### Basic HTML Layout for index.html Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md A foundational HTML structure for the `index.html` layout. It includes essential meta tags, links to CSS frameworks, and a main content area using Jinja templating. ```html {% raw %}{{ '{{' }} site.name {{ '}}' }}{% endraw %}
{% raw %}{{'{{'}} page.content {{'}}'}} {% endraw %}
``` -------------------------------- ### Error: Local theme folder does not exist Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md This error indicates that the specified local theme folder is missing. Create the folder or verify the theme source path. ```shell ba.sake.flatmark.FlatmarkException: Local theme folder does not exist. Please create it or use a valid theme URL. ``` -------------------------------- ### Site Context Configuration Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/template-context.md Defines global site settings propagated from `_config.yaml`. Access site name via `{{ site.name }}`. ```yaml name: "My Site" description: "My site description" base_url: https://example.com search: enabled: true code_highlight: enabled: true math_highlight: enabled: true # languages used in the site langs: [en, bs ...] # categories, folders in content/ categories: blog: label: Blog description: .. # only available in index.md pages, empty otherwise # list of page contexts items: - title: Post 1, url: /blog/post-1.html .. # YAML files from _data/ folder data: my_data_file: "My data value" ``` -------------------------------- ### Create Basic Markdown Content Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/quickstart.md Create a simple markdown file for your site's homepage. This file will be processed by Flatmark to generate the site. ```markdown # Welcome to Flatmark! ``` -------------------------------- ### Configure Local Theme in _config.yaml Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md Specify the local theme to be used by Flatmark. Ensure the theme folder exists in the `_themes/` directory. ```yaml theme: source: my_theme ``` -------------------------------- ### Math Block Rendering Source: https://github.com/sake92/flatmark/blob/main/docs/content/index.md Use the 'math' code block syntax for rendering mathematical expressions. This utilizes KaTeX for rendering. ```markdown ```math x = 5 ``` ``` ```math x = 5 ``` -------------------------------- ### Page-Specific Configuration (YAML Front Matter) Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/configuration.md Configures settings for an individual page, placed at the top of the page file within `---` delimiters. Supports options like title, description, publish date, layout, file extension, publish status, tags, pagination, and theme-specific properties. ```yaml --- title: Hello description: My description publish_date: 2025-01-01 11:11 # in timezone specified in the _config.yaml layout: page.html ext: html # extension of the generated file, default is html publish: yes tags: [scala, java] pagination: enabled: true # enable pagination for this index.md page per_page: 10 # number of items per page sort_by: -publish_date # sort by publish date, descending theme_props: my_theme_prop: my_value # theme specific properties --- {% raw %} # Hello {{ '{{' }}page.title{{ '}}' }} {% endraw %} This is my first post! ``` -------------------------------- ### Search Results Page Configuration Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/search.md To enable the search results page, create a markdown file with this layout. Ensure `search.enabled` is set to `true` in your `_config.yaml`. ```markdown layout: search-results.html ``` -------------------------------- ### Scala Syntax Highlighting Source: https://github.com/sake92/flatmark/blob/main/docs/content/index.md Use the code block syntax with the language specified (e.g., 'scala') for syntax highlighting. This is done via highlight.js. ```markdown ```scala val x = 5 ``` ``` ```scala val x = 5 ``` -------------------------------- ### Paginator Context Details Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/template-context.md Provides pagination information on `index.md` pages, accessible via `{{ paginator.per_page }}`. Includes details on total items, pages, and navigation. ```yaml enabled: true # if pagination is enabled in page config front matter items: # list of page contexts - title: Post 1, url: /blog/post-1.html ... per_page: 10 total_items: 25 total_pages: 3 current: 2 # 1-based index of the current page prev: 1 next: 3 has_prev: true has_next: true prev_url: /blog/index-1.html next_url: /blog/index-3.html ``` -------------------------------- ### Content Directory Structure Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/files-layout.md Defines the organization of content files within the 'content/' directory, including index pages, categories, and translated content. ```bash content/ ├── index.md <-- index page ├── blog <-- the blog category/ │ ├── index.md <-- index page for blog posts │ └── mypost.md <-- one blog post ├── docs <-- the docs category/ │ ├── index.md <-- index page for docs │ └── mypost.md <-- one doc page ├── 404.md <-- 404 not found page └── bs/ <-- translations live in lang-code/ named folders/ ├── index.md └── blog/mypost.md <-- translated post ``` -------------------------------- ### Define Base Layout with Content Block Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md Establishes a base template structure using Jinja's `block` syntax. This allows child templates to define and override specific content sections. ```html {% raw %} {{ '{%' }} block content %} {{ '{%' }} endblock %} {% endraw %} ``` -------------------------------- ### Iterate and Display Pagination Items Source: https://github.com/sake92/flatmark/blob/main/examples/local-theme/_themes/my_custom_theme/_includes/pagination.html Loops through paginator items to display titles and URLs. Use this to render a list of links for paginated content. ```liquid {% for item in paginator.items %}* [{{ item.title }}]({{ item.url }}) {% endfor %} ``` -------------------------------- ### Mermaid Sequence Diagram Source: https://github.com/sake92/flatmark/blob/main/examples/local-theme/content/docs/features.md Illustrates a sequence diagram using Mermaid syntax within a diagram block. ```mermaid sequenceDiagram actor Alice actor Bob Alice->>Bob: Hi Bob Bob->>Alice: Hi Alice ``` -------------------------------- ### Graphviz Diagram Generation Source: https://github.com/sake92/flatmark/blob/main/docs/content/index.md Create Graphviz diagrams using the 'diagram:graphviz' code block syntax. Refer to the Graphviz documentation for more details. ```markdown ```diagram:graphviz digraph G {Hello->World} ``` ``` ```graphviz digraph G {Hello->World} ``` -------------------------------- ### Extend Base Layout in index.html Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md Configures the `index.html` layout to inherit from a base template and define its content within the 'content' block. This promotes code reuse and a consistent structure. ```html {% raw %} {{ '{%' }} extends "base.html" %} {{ '{%' }} block content %} {{'{{'}} page.content {{'}}'}} {{ '{%' }} endblock %} {% endraw %} ``` -------------------------------- ### Page Context Properties Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/template-context.md Contains information specific to the current page, accessible via `{{ page.title }}`. Includes metadata like title, description, and table of contents. ```yaml title: .. description: .. content: .. # not empty only in _layouts/ and _includes/ lang: en publish_date: .. url: .. layout: page.html toc: - level: 1 title: My Heading 1 url: "#my-heading-1" children: - level: 2 title: My Heading 2 url: "#my-heading-2" ... theme_props: my_theme_prop: my_value # theme specific properties ``` -------------------------------- ### Graphviz Diagram Source: https://github.com/sake92/flatmark/blob/main/examples/local-theme/content/docs/features.md Renders a simple directed graph using Graphviz syntax within a diagram block. ```graphviz digraph G {Hello->World} ``` -------------------------------- ### Render Pagination Navigation Links Source: https://github.com/sake92/flatmark/blob/main/examples/local-theme/_themes/my_custom_theme/_includes/pagination.html Conditionally renders previous, current, and next page navigation links if there are multiple pages. Sets 'Prev' and 'Next' URLs based on availability. ```liquid {% if paginator.total_pages > 1 %} {% set prev = paginator.has_prev ? paginator.prev_url : '#' %} {% set next = paginator.has_next ? paginator.next_url : '#' %} [Prev]({{ prev }}) {{ paginator.current }} [Next]({{ next }}) {% endif %} ``` -------------------------------- ### Error: Template not found Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/custom_local_theme.md This error occurs when a required template file (e.g., 'index.html', 'page.html') is not found in the expected locations. Ensure layout files are correctly placed within the theme or site directories. ```shell ba.sake.flatmark.FlatmarkException: Template 'index.html' not found in content/ or _layouts/ or theme _layouts/. ``` -------------------------------- ### Scala Code Block Source: https://github.com/sake92/flatmark/blob/main/examples/local-theme/content/docs/features.md Demonstrates a simple Scala code snippet within a fenced code block. ```scala val x = 1 ``` -------------------------------- ### Set Default Language in _config.yaml Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/multilang.md Configure the default language for your Flatmark site. This file should be placed in the root of your site folder. ```yaml lang: en ``` -------------------------------- ### Loop Through Data Files in Markdown Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/data-files.md Iterate over data loaded from a YAML file using a Liquid `for` loop within a Markdown file. This allows for dynamic content generation based on your data. ```markdown {% raw %}{{% for author in site.data.authors %}} - {{ author.name }}, skills: {{ author.skills|join(', ') }} {% endfor %}{% endraw %} ``` -------------------------------- ### Mermaid Diagram Generation Source: https://github.com/sake92/flatmark/blob/main/docs/content/index.md Create Mermaid diagrams using the 'diagram:mermaid' code block syntax. Refer to the Mermaid documentation for more details. ```markdown ```diagram:mermaid sequenceDiagram actor Alice actor Bob Alice->>Bob: Hi Bob Bob->>Alice: Hi Alice ``` ``` ```mermaid sequenceDiagram actor Alice actor Bob Alice->>Bob: Hi Bob Bob->>Alice: Hi Alice ``` -------------------------------- ### Search Index JSON Structure Source: https://github.com/sake92/flatmark/blob/main/docs/content/reference/search.md This is the structure of the search index file generated by Flatmark. It contains an array of objects, each representing a page with its text, title, and URL. ```json [ { "text": "Text of the page", "title": "Title of the page", "url": "/path/to/page.html" }, ... ] ``` -------------------------------- ### Math Block Source: https://github.com/sake92/flatmark/blob/main/examples/local-theme/content/docs/features.md Shows a mathematical expression rendered within a math block. ```math x = 5 ``` -------------------------------- ### Extending Templates in Flatmark Source: https://github.com/sake92/flatmark/blob/main/docs/content/howtos/gotchas.md When extending a template, you can only override existing blocks defined in the base template. New blocks cannot be added, nor can content be inserted outside of defined blocks. ```html {% extends "base.html" %} {% block title %} {{page.title}} {% endblock %} --- cant add this!!! {% block hack %} cant add this either!!! {% endblock %} ``` -------------------------------- ### Simple Scala Variable Source: https://github.com/sake92/flatmark/blob/main/examples/simple/content/index.md Defines a simple string variable in Scala. ```scala def x = "bla" ``` -------------------------------- ### Define Author Data in YAML Source: https://github.com/sake92/flatmark/blob/main/docs/content/tutorials/data-files.md Store structured data for authors in a YAML file. This data can be accessed and used within your site's templates. ```yaml - name: Sakib skills: [scala, java, python] - name: Senjin skills: [scala, java, javascript] ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.