{"id":13520273,"url":"https://github.com/yagarea/jektex","last_synced_at":"2025-10-08T06:51:48.197Z","repository":{"id":37257921,"uuid":"457531288","full_name":"yagarea/jektex","owner":"yagarea","description":"A Jekyll plugin for fast server-side cached LaTeX rendering, with support for macros. Enjoy the comfort of LaTeX and Markdown without cluttering your site with bloated JavaScript.","archived":false,"fork":false,"pushed_at":"2025-07-21T07:46:13.000Z","size":330,"stargazers_count":36,"open_issues_count":4,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-30T06:15:04.016Z","etag":null,"topics":["bundle","bundler","gem","hacktoberfest","jekyll","jekyll-plugin","katex","katex-plugin","katex-support","kramdown","latex","markdown","nojavascript","nojs","ruby-gem","static-site","static-site-generator","static-website","tex","yaml"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/jektex","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yagarea.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-09T21:17:07.000Z","updated_at":"2025-08-21T18:08:22.000Z","dependencies_parsed_at":"2023-01-21T07:03:00.566Z","dependency_job_id":"a5d640a4-77b1-43d9-8c4a-724d0a146ef0","html_url":"https://github.com/yagarea/jektex","commit_stats":{"total_commits":125,"total_committers":2,"mean_commits":62.5,"dds":0.008000000000000007,"last_synced_commit":"a4f81bc220623e95838d289d803c3b5a843d961b"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/yagarea/jektex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yagarea%2Fjektex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yagarea%2Fjektex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yagarea%2Fjektex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yagarea%2Fjektex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yagarea","download_url":"https://codeload.github.com/yagarea/jektex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yagarea%2Fjektex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278903006,"owners_count":26065786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundle","bundler","gem","hacktoberfest","jekyll","jekyll-plugin","katex","katex-plugin","katex-support","kramdown","latex","markdown","nojavascript","nojs","ruby-gem","static-site","static-site-generator","static-website","tex","yaml"],"created_at":"2024-08-01T05:02:16.246Z","updated_at":"2025-10-08T06:51:48.147Z","avatar_url":"https://github.com/yagarea.png","language":"Ruby","funding_links":[],"categories":["Markup \u0026 Markdown Converters","Ruby"],"sub_categories":[],"readme":"[![Gem Version](https://badge.fury.io/rb/jektex.svg)](https://rubygems.org/gems/jektex)\n\n# ![Jektex](https://blackblog.cz/assets/img/projects/jektex.svg)\nA Jekyll plugin for blazing-fast server-side cached LaTeX rendering, with support for macros.\nEnjoy the comfort of LaTeX and Markdown without cluttering your site with bloated JavaScript.\nThis project is [endorsed by KaTeX.org](https://katex.org/docs/libs#jekyll).\n\n## Features\n- Renders LaTeX formulas during Jekyll rendering\n- Works without any client-side JavaScript\n- Is faster than any other server-side Jekyll LaTeX renderer\n- Supports user-defined global macros\n- Has I/O-efficient caching system\n- Dynamically informs about the number of expressions during rendering\n- Is very easy to setup\n- Doesn't interfere with Jekyll workflow and project structure\n- Marks invalid expressions in document, printing its location during rendering\n- Is highly configurable with sensible defaults\n- Makes sure that cache does not contain expression rendered with outdated configuration\n- Supports two major LaTeX notations\n\n## Usage\nJektex supports both the built-in Kramdown math notation, and the newer LaTeX-only math notation.\n\n### Kramdown notation\n**Inline formula**  \nPut formula between two pairs of dollar signs (`$$`) inside of paragraph.\n```latex\nLorem ipsum dolor sit amet, consectetur $$e^{i\\theta}=\\cos(\\theta)+i\\sin(\\theta)$$\nadipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n```\n\n**Display formula**  \nPut formula between two pairs of dollar signs (`$$`) and surround it with two empty lines.\n```latex\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor\nincididunt ut labore et dolore magna aliqua.\n\n$$ \\left[ \\frac{-\\hbar^2}{2\\mu}\\nabla^2 + V(\\mathbf{r},t)\\right] \\Psi(\\mathbf{r},t) $$\n\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex\nea commodo consequat.\n```\n\n_Why Jektex does not use conventional single `$` for inline formulas and double `$$` for\ndisplay mode?  \nThis is how [kramdown](https://kramdown.gettalong.org/) (Jekyll's markdown parser) works \nso I decided to respect this convention. It makes this plugin more consistent and universal.\nSee [this issue](https://github.com/gettalong/kramdown/issues/762) for more context._\n\n\n### LaTex math mode notation\n**Inline formula**  \nPut formula between two escaped brackets `\\(` `\\)`.\nIts position in the text does not matter.\n```latex\nLorem ipsum dolor sit amet, consectetur \\(e^{i\\theta}=\\cos(\\theta)+i\\sin(\\theta)\\)\nadipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n```\n\n**Display formula**  \nPut formula between two escaped square brackets `\\[` `\\]`.\nIts position in the text does not matter.\n```latex\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor\nincididunt ut labore et dolore magna aliqua.\n\n\\[ \\left[ \\frac{-\\hbar^2}{2\\mu}\\nabla^2 + V(\\mathbf{r},t)\\right] \\Psi(\\mathbf{r},t) \\]\n\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex\nea commodo consequat.\n```\n\n### Logo macro\nThere is a build in macro for jektex logo. You can use it as `\\jektex`.\n\n### Config\nJektex is highly configurable via your `_config.yml` file.\n\n**Disabling cache**  \nYou can disable caching with `disable_disk_cache = true` in `_config.yml`.\nCaching is enabled by default.\nYou can find more information on [Jekyll's official website](https://jekyllrb.com/docs/configuration/options/).\n\n**Setting cache location**  \nBy default, Jektex cache will be saved in `.jekyll-cache` directory.\nThis results in its deletion when you call `jekyll clean`.\nTo prevent cache deletion or to change the cache location, you can specify `cache_dir` in `_config.yml`:\n```yaml\njektex:\n  cache_dir: \".jektex-cache\"\n```\n\n**Ignoring files**  \nBy default, Jektex tries to render LaTeX in all files rendered by Jekyll.\nThis can sometimes be undesirable, for example when rendering an _RSS feed_ with excerpts containing LaTeX.\nJektex solves this by using the `ignore` option:\n```yaml\njektex:\n  ignore: [\"*.xml\", \"README.md\", \"_drafts/*\" ]\n```\n\nYou can use conventional wild cards using `*`.\nThis example configuration ignores all `.xml` files, `README.md` and all files in the `_drafts` directory.\n\nAnother way to ignore specific posts is setting the `jektex` attribute in front matter to `false`:\n```yaml\n---\ntitle: \"How Jektex works\"\ncategory: \"Development\"\njektex: false\nlayout: post\n---\n```\n\nSetting `jektex` tag to `true` or not setting at all will result in Jektex rendering LaTeX expressions in that post.\n\n**Using macros**  \nYou can define global macros:\n```yaml\njektex:\n  macros:\n    - [\"\\\\Q\", \"\\\\mathbb{Q}\"]\n    - [\"\\\\C\", \"\\\\mathbb{C}\"]\n```\nAnd yes, you have to escape the backlash (`\\`) with another backlash.\nThis is due to the [yaml specification](https://yaml.org/).\n\nYou can define macros with parameters:\n```yaml\njektex:\n  macros:\n    - [\"\\\\vec\", \"\\\\mathbf{#1}\"]\n    - [\"\\\\addBar\", \"\\\\bar{#1}\"]\n```\nThis simulates behaviour of LaTeX `\\newcommand`.\n\n**Silencing Jektex output**  \nJektex periodically informs the user about rendered/cached equations.\nIf this is not desired, you can set the `silent` option (`false` by default).\n```yaml\njektex:\n  silent: true\n```\n\n**Complete examples**  \nRecommended config:\n```yaml\njektex:\n  cache_dir: \".jektex-cache\"\n  ignore: [\"*.xml\"]\n  silent: false\n  macros:\n    - [\"\\\\Q\", \"\\\\mathbb{Q}\"]\n    - [\"\\\\C\", \"\\\\mathbb{C}\"]\n```\n\nHaving no configuration is equivalent to this:\n```yaml\njektex:\n  cache_dir: \".jekyll-cache\"\n  ignore: []\n  silent: false\n  macros: []\n```\n\n## Installation\nThis plugin is available as a [RubyGem](https://rubygems.org/gems/jektex).\n\n**Using bundler**  \nAdd Jektex to your `Gemfile`:\n```ruby\ngroup :jekyll_plugins do\n    gem \"jektex\"\nend\n```\n\nand run `bundle install`\n\n**Without bundler**  \nRun `gem install jektex`\n\n**After installation**  \nAdd Jektex to your plugin list in your `_config.yml` file\n```yaml\nplugins:\n    - jektex\n```\n\nand don't forget to add `katex.min.css` to you HTML head:\n```html\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css\" integrity=\"sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ\" crossorigin=\"anonymous\"\u003e\n```\nIt is much better practice to download the [**css** file](https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css) and load it as an asset from your server directly.\nYou can find more information on [KaTeX's website](https://katex.org/docs/browser.html).\n\n## Contributions and bug reports\nFeel free to report any bugs or even make feature request in [issues on official repository](https://github.com/yagarea/jektex/issues).\nI am opened for pull requests as well.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyagarea%2Fjektex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyagarea%2Fjektex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyagarea%2Fjektex/lists"}