{"id":13594817,"url":"https://github.com/sile-typesetter/sile","last_synced_at":"2025-05-13T19:03:02.520Z","repository":{"id":12239985,"uuid":"14852193","full_name":"sile-typesetter/sile","owner":"sile-typesetter","description":"The SILE Typesetter — Simon’s Improved Layout Engine","archived":false,"fork":false,"pushed_at":"2025-05-05T21:29:16.000Z","size":57554,"stargazers_count":1702,"open_issues_count":273,"forks_count":102,"subscribers_count":49,"default_branch":"master","last_synced_at":"2025-05-05T22:25:32.280Z","etag":null,"topics":["lua","pdf","pdf-generation","publishing","sile","tex","typesetting","typesetting-system"],"latest_commit_sha":null,"homepage":"https://sile-typesetter.org","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sile-typesetter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["alerque","simoncozens"]}},"created_at":"2013-12-02T03:49:24.000Z","updated_at":"2025-05-05T19:39:53.000Z","dependencies_parsed_at":"2024-01-09T19:36:38.682Z","dependency_job_id":"e211f736-2973-4dcd-bf4b-42299e122273","html_url":"https://github.com/sile-typesetter/sile","commit_stats":{"total_commits":4847,"total_committers":69,"mean_commits":70.2463768115942,"dds":0.5217660408500103,"last_synced_commit":"51d33b6b4d88524dc661245522e987d7fae9beee"},"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fsile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fsile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fsile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sile-typesetter%2Fsile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sile-typesetter","download_url":"https://codeload.github.com/sile-typesetter/sile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010792,"owners_count":21998993,"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","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":["lua","pdf","pdf-generation","publishing","sile","tex","typesetting","typesetting-system"],"created_at":"2024-08-01T16:01:39.516Z","updated_at":"2025-05-13T19:03:02.484Z","avatar_url":"https://github.com/sile-typesetter.png","language":"Lua","funding_links":["https://github.com/sponsors/alerque","https://github.com/sponsors/simoncozens"],"categories":["Technical details","Lua","LUA"],"sub_categories":["Check the pre-requisites"],"readme":"[![Actions Build Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/sile/build.yml?branch=master\u0026label=Linux%20Build\u0026logo=Github)](https://github.com/sile-typesetter/sile/actions?workflow=Build)\n[![Cirrus Build Status](https://img.shields.io/cirrus/github/sile-typesetter/sile?label=FreeBSD%20Build\u0026logo=freebsd)](https://cirrus-ci.com/github/sile-typesetter/sile/master)\n[![Docker Build Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/sile/deploy.yml?branch=master\u0026label=Docker%20Build\u0026logo=Docker)](https://github.com/sile-typesetter/sile/pkgs/container/sile)\n[![Azure Build Status](https://img.shields.io/azure-devops/build/sile-typesetter/069c3e31-ee59-4bd6-b395-1f1059acd8db/1?label=Windows%20Build\u0026logo=Azuredevops)](https://dev.azure.com/sile-typesetter/sile/_build/latest?definitionId=1\u0026branchName=master)\u003cbr /\u003e\n[![Luacheck Lint Status](https://img.shields.io/github/actions/workflow/status/sile-typesetter/sile/luacheck.yml?branch=master\u0026label=Luacheck\u0026logo=Lua)](https://github.com/sile-typesetter/sile/actions?workflow=Luacheck)\n[![Coveralls Coverage Status](https://img.shields.io/coveralls/github/sile-typesetter/sile?label=Coverage\u0026logo=Coveralls)](https://coveralls.io/github/sile-typesetter/sile?branch=master)\u003cbr /\u003e\n[![Chat on Gitter](https://img.shields.io/gitter/room/sile-typesetter/sile?color=blue\u0026label=Chat\u0026logo=Gitter)](https://gitter.im/sile-typesetter/sile?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)\n[![Commitizen Friendly](https://img.shields.io/badge/Commitizen-friendly-blue.svg)](http://commitizen.github.io/cz-cli/)\n\n## What is SILE?\n\nSILE is a [typesetting][typesetting] system; its job is to produce beautiful printed documents.\nConceptually, SILE is similar to [TeX][tex]—from which it borrows some concepts and algorithms—but the similarities end there.\nRather than being a derivative of the TeX family SILE is a new typesetting and layout engine written from the ground up using modern technologies and borrowing some ideas from graphical systems such as [InDesign][indesign].\n\n## Where does it run?\n\nSILE can be [downloaded \u0026 installed](#download-and-installation) to your system or [run remotely as a CI job](#use-as-a-CI-job).\n\n## What can I do with SILE (that I can’t do with TeX)?\n\nFirst, have a look at the [usage examples gallery][examples]. SILE allows you to:\n\n* Produce complex document layouts using frames.\n\n* Easily extend the typesetting system in a high-level programming language (Lua).\n\n* Directly process XML to PDF without the use of XSL stylesheets.\n\n* Typeset text on a grid.\n\n## Download and Installation\n\n### For macOS\n\nA formula is available for [Homebrew][brew] that can install either stable or head versions.\nFor the latest prebuilt stable release:\n\n```console\n$ brew install sile\n```\n\nOr to build and install from the latest git commit:\n\n```console\n$ brew install sile --HEAD\n```\n\nNote the Homebrew package does not automatically install the [default font](#default-font).\nThe easiest way to install Gentium Plus is through the [Homebrew Fonts caskroom][brewfonts]:\n\n```console\n$ brew tap homebrew/cask-fonts\n$ brew install --cask font-gentium-plus\n```\n\n### For Linux\n\n#### Arch Linux\n\nArch Linux has a prebuilt [SILE package][arch-sile] in the official package repository:\n\n```console\n$ pacman -S sile\n```\n\nThe official package uses LuaJIT.\nIf you install LuaRocks for use with SILE via `pacman`, use the `lua51-*` variants to match LuaJIT.\n\n#### Fedora\n\nFedora Linux has SILE in their official repositories. To install run:\n\n```console\n$ dnf install sile\n```\n\nNot all the fonts are not installed by default, to install them:\n\n```console\n$ dnf install sil-gentium-plus-fonts alerque-libertinus-fonts hack-fonts\n```\n\n#### OpenSUSE\n\nOpenSUSE has official packages ready to install the usual way:\n\n```console\n$ zypper install sile\n```\n\n#### NixOS\n\nA [Nix `sile` package][nix] is available in both the stable and unstable channels;\n  the unstable channel having the latest stable SILE releases and the stable channel being frozen on NixOS releases.\nYou can use all the usual Nix tricks including adding SILE into a `nix shell` environment or executing it directly with `nix run`.\n\nSee additional usage notes in the [Nix section](#nix).\n\n#### Ubuntu\n\nA [PPA][ppa] is available for Ubuntu users with packages of SILE and all the necessary dependencies.\nWe introduced support starting with Bionic (18.04) and maintain packages for all Ubuntu release series since for as long as they are supported by Canonical.\n\n```console\n$ add-apt-repository ppa:sile-typesetter/sile\n$ apt-get update\n$ apt-get install sile\n```\n\n#### Void Linux\n\nVoid Linux packages are available in the default package manager.\n\n#### Other\n\nOther Linux distros may install via [source](#from-source), via [Linux Brew][linuxbrew], or via [Nix](#nixos).\n\n### For BSD\n\nInstall from OpenBSD [ports][], via [source](#from-source), or via [Nix](#nixos).\n\n### For Windows\n\nThere is no installer yet (track the status in [issue #410](https://github.com/sile-typesetter/sile/issues/410)).\nNobody is currently maintaining Windows compatibility in SILE and we expect the state to be a bit broken.\nUsers of WSL (Windows Subsystem for Linux) may use the package manager of their choice depending on the system installed, including the respective [Arch Linux](#arch-linux) or [Ubuntu](#ubuntu) packages, [Linux Brew][linuxbrew], [source](#from-source), or via [Nix][#nixos].\n\nSome early work is present in the repository that should enable builds via CMake and Visual Studio, see discussion in [issue #567](https://github.com/sile-typesetter/sile/pull/567), but it needs a refresh for current dependencies.\nPrebuilt Windows binaries are supposed to be generated by the Azure [build pipeline][azure] and may be downloaded by selecting a build, opening the Windows job, selecting the artifact link from the final stage, and using the download button next to the sile folder.\n\n### Multi-Platform \u0026 Containers\n\n#### Docker\n\nDocker images are available as [siletypesetter/sile](https://hub.docker.com/repository/docker/siletypesetter/sile).\nReleased versions are available as tagged containers matching the release (e.g. `v0.10.0`).\nAdditionally the latest release will be tagged `latest`, and a `master` tag is also available with the freshest development build.\n\nIn order to be useful you need to tell the Docker run command a way to reach your source documents.\nThis is done by mounting your project directory inside the container.\nThis also gives SILE a place to write the output.\nThe user and group IDs of the Docker user will be automatically adjusted to match those of the directory you mounted.\n\nYou may find it easiest to do all this with an alias like this:\n\n```console\n$ alias sile='docker run -it --volume \"$(pwd):/data\" siletypesetter/sile:latest'\n$ sile input.sil\n```\n\nOne notable issue with using SILE from a Docker container is that by default it will not have access to your system’s fonts.\nTo work around this you can map a folder of fonts (in any organization usable by fontconfig) into the container.\nThis could be your system’s default font directory, your user one, a folder with project specific resources, or anything of your choosing.\nYou can see where fonts are found on your system using `fc-list`.\nThe path of your choosing from the host system should be mounted as a volume on `/fonts` inside the container like this:\n\n```console\n$ docker run -it --volume \"/usr/share/fonts:/fonts\" --volume \"$(pwd):/data\" siletypesetter/sile:latest\n```\n\n#### Nix\n\nThe `nix` package manager is available as a standalone package manager on many platforms other than NixOS including most Linux and BSD distributions, macOS, and even for Windows via WSL;\n  and thus presents a viable alternative way to run SILE on most systems.\n\n[Nix packages][nix] are available in both the stable and unstable channels.\nWe recommend the unstable channel because all fresh packages (including stable SILE releases) land there first and eventually trickle down to the stable channel.\nYou can use all the usual Nix tricks including launching a new shell with the `sile` command available or running it directly from any shell:\n\n```console\n# Launch a new shell with SILE available\n$ nix shell nixpkgs/nixpkgs-unstable#sile\n$ sile \u003carguments\u003e\n\n# Run SILE directly as a single command\n$ nix run nixpkgs/nixpkgs-unstable#sile -- \u003carguments\u003e\n```\n\nThe SILE source repository is also a [Nix Flake][nix-flakes].\nThis means you can run any arbitrary tagged version, branch, or commit with a single command.\nThis is an easy way to run SILE on other platforms, but also to test other versions or run the latest development version of SILE.\n\n```console\n# Explicitly run a tagged version\n$ nix run github:sile-typesetter/sile/v0.14.13 -- \u003carguments\u003e\n\n# Use the master branch HEAD that will become the next minor release\n$ nix run github:sile-typesetter/sile -- \u003csile arguments\u003e\n\n# Run the develop branch HEAD that will become the next major release\n$ nix run github:sile-typesetter/sile/develop -- \u003csile arguments\u003e\n```\n\n### From Source\n\nSILE source code can be downloaded from [its website][sile] or directly from [the GitHub releases page][releases].\n\nSILE is completely programmable using the Lua programming language.\nAs of v0.15.0, the CLI you actually execute is a Rust binary with a Lua VM built in.\n(For compatibility and demonstration purposes a pure Lua version of the CLI is still available as \\code{sile-lua}.)\nThe Rust binary can be built based on your system's Lua sources or use its own vendored Lua sources.\nAll SILE's Lua code takes a lowest-common-denominator approach to Lua compatibility.\nAny of Lua 5.1, 5.2, 5.3, 5.4, or LuaJIT (2.0, 2.1, or OpenResty) are fully supported.\nCompiling it to match your system's Lua version has the advantage of making it easy to access system installed Lua Rocks, but this is not a requirement.\n\nCompiling from sources will require both a Rust toolchain and Lua sources.\nAt runtime no Rust tooling is required, and the system Lua interpreter is not actually used.\n\nIt also relies on external libraries to access fonts and write PDF files.\nIts preferred combination of libraries is [HarfBuzz][harfbuzz] and [libtexpdf][], a PDF creation library extracted from TeX.\nHarfBuzz (minimum version 2.7.4) should be available from your operating system’s package manager.\nFor HarfBuzz to work you will also need fontconfig installed.\nSILE also requires the [ICU][icu] libraries for Unicode handling.\n\nOn macOS, ICU can be installed via Homebrew:\n\n```console\n$ brew install icu4c\n```\n\nAfter that, you might need to set environment variables.\nIf you try to `brew link` and you get a series of messages including something like these two lines, you will need to run that export line to correctly set your path:\n\n    For pkg-config to find icu4c you may need to set:\n      export PKG_CONFIG_PATH=\"/usr/local/opt/icu4c/lib/pkgconfig\"\n\nOptionally you may install the Lua libraries listed in the [rockspec][] to your system (using either your system’s package manager or [luarocks][] (`luarocks install --only-deps sile-dev-1.rockspec`).\nBy default all the required Lua libraries will be downloaded and bundled alongside the SILE the installation.\nIf you downloaded a source tarball these dependencies are included.\nIf you are using a Git clone of the source repository the build system will require `luarocks` to fetch them during build.\nNote that OpenSSL development headers will be required for one of the Lua modules to compile¹.\nIf your system has all the required packages already you may add `--with-system-luarocks` to the `./configure` command to avoid bundling them.\n\n¹ \u003csub\u003eOpenSSL development headers are required to build *luasec*, please make sure they are setup _BEFORE_ trying to build SILE!\nIf you use your system’s Luarocks packages this will be done for you, otherwise make sure you can compile luasec.\nYou can try just this step in isolation before building SILE using `luarocks --tree=/tmp install luasec`.\u003c/sub\u003e\n\nIf you are building from a git clone, start by running the script to setup your environment (if you are using the source tarball this is unnecessary):\n\n```console\n$ ./bootstrap.sh\n```\n\nIf you just plan on installing and using SILE, the default configure options (plus any Lua related options discussed above) should be fine.\nIf you plan on developing SILE itself (whether to just tinker with it for your own use or contribute upstream) there is one particularly useful configuration option.\nYou can add `--enable-developer-mode` will set the 'installed data' directory to the source location which will enable the compiled binary to run directly from the source directory without being installed at all.\nAdditionally it will enable checks for tooling we expect SILE contributors to have such as tools used for testing.\nUsing this options also enables a number of targets that wouldn’t normally be needed by end users such as `make regressions`.\n\nOnce your dependencies are installed and you know what options you want, it is time to configure the sources, then build them.\n\n```console\n$ ./configure\n$ make\n```\n\nIf you just want to mess with SILE locally you can stop here (especially if you used `--enable-developer-mode`).\nHowever to actually install, you will need to run the installation command with system permissions.\n\n```console\n$ sudo make install\n```\n\nOn some systems you may also need to make the system aware of the newly installed libraries before first use:\n\n```console\n$ ldconfig\n```\n\n### Default Font\n\nSince SILE v0.9.5, the default font has been Gentium Plus which is freely available from [SIL’s site][gentium].\n(Previously we used Gentium Basic, but that’s getting harder to get hold of.)\nThe math package uses [Libertinus Math][libertinus] by default to render formulas.\nAdditionally, monospace text by default is set in [Hack][hack].\nIt is not absolutely required that you install default fonts, but if this font is not installed on your system you won’t be able to use the examples without modification.\n\n### Testing the installation\n\nIf all goes well, after installation you should be able to render a sample document.\nTry creating a file `test.sil` with this content:\n\n```sil\n\\begin{document}\nHello world!\n\\end{document}\n```\n\nAnd render it to a PDF like this:\n\n```console\n$ sile test.sil\nSILE v0.12.5 (Lua 5.4)\n\u003ctest.sil\u003e\n[1]\n```\n\nYou should now have a PDF file `test.pdf` ready for review.\n\n## Use as a CI job\n\nThere are actually many ways to run SILE remotely as part of a CI work flow.\nBecause packages are available for many platforms, one way would be to just use your platforms native package installation system to pull them into whatever CI runner environment you already use.\nAnother way is to pull in the prebuilt Docker container and run that.\n\nAs a case study, here is how a workflow could be setup in GitHub Actions:\n\n```yaml\nname: SILE\non: [ push, pull_request ]\njobs:\n  sile:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Render document with SILE\n        uses: sile-typesetter/sile@v0\n        with:\n          args: my-document.sil\n```\n\nAdd to your repository as `.github/workflows/sile.yaml`.\nThis work flow assumes your project has a source file `my-document.sil` and will leave behind a `my-document.pdf`.\nNote the comments in [the section about Docker](#docker) regarding version tags.\n\n## Installing third-party packages\n\nThird-party SILE packages can be installed using the `luarocks` package manager.\nPackages may be hosted anywhere, either on the default [luarocks.org](https://luarocks.org/) repository, on 3rd party repositories, or even private repositories.\nNote some servers support more than one manifest, so you may need a `--server` argument to pick the right one.\n\nThird party packages must be installed for the same version of Lua that SILE uses.\nOn systems with more than one Lua version installed, *and* where SILE does not use the default one you may need to specify the version manually.\nIn these examples, we'll ask SILE directory which version it is running.\n\nFor example, to install [markdown.sile](https://github.com/Omikhleia/markdown.sile) (a plugin that provides a SILE inputter that reads and processes Markdown documents) one could run:\n\n```console\n$ luarocks --lua-version $(sile -q \u003c\u003c\u003c SILE.lua_version) install markdown.sile\n```\n\nBy default, this will try to install the package to your system (the `--global` option).\nThis may not be desired (and usually requires root access), but there are two other places to install plugins.\nFirst, you may add `--tree lua_modules` to install them in a directory called `lua_modules` in the current directory.\nIn this case (and assuming this is the same directory as your document) SILE will automatically find such plugins.\n\nAdditionally, you may install them to your user profile by adding `--local` when installing.\nYou may also install them to any other directory besides 'lua_modules' relative to your input files.\nIn these cases you will also need instruct SILE to check for plugins in your preferred path since Lua (and hence SILE) does not do so by default.\nThis can be done in either of two ways.\nYou can set an environment variable by running `eval $(luarocks --lua-version $(sile -q \u003c\u003c\u003c SILE.lua_version) path --local)` (or the `--tree path` of your choice).\nThis can be done once per shell before running SILE or from your shell’s initialization script to make it permanent.\nFor a simpler incantation that needs to be typed into the SILE command on each use, you can also specify a tree by passing a `--luarocks-tree path` argument to SILE itself.\n\n## Finding Out More\n\nPlease read the [full SILE manual][doc] for more information about what SILE is and how it can help you.\nThere are example documents (source and PDF) [on the SILE website][examples].\nThere’s also an [FAQ][faq] available.\n\n## Contact\n\nPlease report bugs and send patches and pull requests at the [github repository][github].\nFor questions and discussion, please join the [mailing list][list-en].\n\n## License Terms\n\nSILE is distributed under the [MIT license][license].\n\n  [alerque-arch]: https://wiki.archlinux.org/index.php/Unofficial_user_repositories#alerque\n  [arch-sile]: https://archlinux.org/packages/extra/x86_64/sile/\n  [aur]: https://wiki.archlinux.org/index.php/Arch_User_Repository\n  [azure]: https://dev.azure.com/sile-typesetter/sile/_build?view=runs\n  [brew]: http://brew.sh\n  [brewfonts]: https://github.com/Homebrew/homebrew-cask-fonts\n  [copr]: https://copr.fedorainfracloud.org/coprs/jonny/SILE/\n  [doc]: http://sile-typesetter.org/manual/sile-latest.pdf\n  [examples]: http://www.sile-typesetter.org/examples/\n  [faq]: https://github.com/sile-typesetter/sile/wiki/faq\n  [gentium]: http://software.sil.org/gentium/download/\n  [github]: https://github.com/sile-typesetter/sile\n  [hack]: https://sourcefoundry.org/hack/\n  [harfbuzz]: http://www.freedesktop.org/wiki/Software/HarfBuzz/\n  [icu]: http://icu-project.org\n  [indesign]: https://en.wikipedia.org/wiki/Adobe_InDesign\n  [libertinus]: https://github.com/alerque/libertinus\n  [libtexpdf]: https://github.com/sile-typesetter/libtexpdf\n  [license]: http://choosealicense.com/licenses/mit/\n  [linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux\n  [list-en]: https://groups.google.com/d/forum/sile-users\n  [luarocks]: http://luarocks.org/en/Download\n  [nix-flakes]: https://wiki.nixos.org/wiki/Flakes#Installing_flakes\n  [nix]: https://nixos.org/nix\n  [ports]: http://ports.su/print/sile\n  [ppa]: https://launchpad.net/~sile-typesetter/+archive/ubuntu/sile\n  [releases]: https://github.com/sile-typesetter/sile/releases\n  [rockspec]: https://github.com/sile-typesetter/sile/blob/master/sile-dev-1.rockspec\n  [sile]: http://www.sile-typesetter.org/\n  [tex]: https://en.wikipedia.org/wiki/TeX\n  [typesetting]: https://en.wikipedia.org/wiki/Typesetting\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsile-typesetter%2Fsile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsile-typesetter%2Fsile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsile-typesetter%2Fsile/lists"}