{"id":17594891,"url":"https://github.com/pinnaculum/iraty","last_synced_at":"2025-08-18T22:31:33.779Z","repository":{"id":178117664,"uuid":"502396305","full_name":"pinnaculum/iraty","owner":"pinnaculum","description":"Python tool to easily create and publish static websites on the dweb (mirror of https://gitlab.com/cipres/iraty)","archived":false,"fork":false,"pushed_at":"2022-06-15T18:35:13.000Z","size":132,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-31T00:09:44.512Z","etag":null,"topics":["distributed","dweb","ipfs","jinja2","omegaconf","python","static-website","yaml"],"latest_commit_sha":null,"homepage":"https://iraty.gitlab.io","language":"Python","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/pinnaculum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"pinnaculum","liberapay":"galacteek"}},"created_at":"2022-06-11T16:12:07.000Z","updated_at":"2024-05-06T00:52:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"c91180b8-304c-4efd-b8e5-b5de6dfafadf","html_url":"https://github.com/pinnaculum/iraty","commit_stats":null,"previous_names":["pinnaculum/iraty"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinnaculum%2Firaty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinnaculum%2Firaty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinnaculum%2Firaty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinnaculum%2Firaty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinnaculum","download_url":"https://codeload.github.com/pinnaculum/iraty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230284070,"owners_count":18202330,"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":["distributed","dweb","ipfs","jinja2","omegaconf","python","static-website","yaml"],"created_at":"2024-10-22T07:12:19.772Z","updated_at":"2024-12-18T14:17:18.143Z","avatar_url":"https://github.com/pinnaculum.png","language":"Python","funding_links":["https://github.com/sponsors/pinnaculum","https://liberapay.com/galacteek"],"categories":[],"sub_categories":[],"readme":"![logo](https://gitlab.com/cipres/iraty/-/raw/master/media/img/logo-128.png)\n\n*iraty* (partly named after the *Ossau-Iraty* French cheese) is a Python tool to\neasily create and publish static websites\nusing a simple template syntax. Documents are written in YAML and can make use\nof *resolvers* (special functions called by the\n[YAML engine](https://github.com/omry/omegaconf)).\n\nThis tool is designed with the distributed web in mind (but you can run it in\na *standalone* mode), and the HTML documents produced can\neasily be puslished to IPFS. Because YAML enforces indentation, the structure\nof your documents is easy to read and this lets you concentrate on the content.\nA collection of *classless* CSS themes is provided to make styling easy.\n\n*If you think that using bits of YAML to create websites is insane and totally\nstupid, you'll feel right at home here.*\n\n# Install\n\nYou only need python3. Install from the latest released wheel using pip:\n\n```sh\npip install --user -U \"https://gitlab.com/cipres/iraty/-/releases/1.1.0/downloads/iraty-1.1.0-py3-none-any.whl\"\n```\n\nOr clone [the git repo](https://gitlab.com/cipres/iraty) and install it with:\n\n```sh\ngit clone \"https://gitlab.com/cipres/iraty.git\" \u0026\u0026 cd iraty\npip install -e .\n```\n\nThere's also a docker image (see [how to run it with docker](#docker)):\n\n```sh\nsudo docker pull registry.gitlab.com/cipres/iraty:latest\n```\n\n# Usage\n\nThe following commands are supported:\n\n* **run**: generate the website\n* **ipfs-deploy**: same as **run**, but always imports to IPFS\n* **node-config** (or **nc**): configure an IPFS node (the default node is *local*)\n* **serve**: generate the website and serve it over HTTP\n* **lint**: check the YAML syntax of an input directory\n* **list-resolvers**: list all available resolvers and their documentation\n* **list-themes**: list all available themes\n\nThe **run** command accepts a directory or single file. YAML files (files with\nthe *.yaml* or *.yml* extension) inside the source directory will be converted.\nThe output directory path by default is **public**\n(use **-o** to set another output directory).\nIf you use **--ipfs** or **-i**, the website will be imported to IPFS and\nthe CID of the root IPFS directory is printed to stdout.\nUse **--theme** or **-t** to change the theme (the default theme is\n*mercury*, use **-t null** to use no theme).\n\n## Generate the website\n\n```sh\niraty run site\niraty --theme=sakura-dark -o html run site\n\niraty --ipfs run site\niraty --ipfs run site|ipfs ls\n```\n\n## Configure an IPFS node\n\nCreate a new config for an IPFS node with the **node-config** command\n(this will open your *EDITOR*), and specify the node you want to use\nwith **--node**. The default IPFS node configuration is called *local*.\nYou will be asked if you want to register the remote pinning\nservices listed in the config.\n\n```sh\niraty node-config ripfs1\niraty --node=ripfs1 ipfs-deploy site\n```\nIf you want to force the use of a specific IPFS node (will soon be\ndeprecated by **--node** and **node-config**):\n\n```sh\niraty --ipfs-maddr '/dns/localhost/tcp/5051/http' ipfs-deploy site\n```\n\n## Serve the website over HTTP\n\nIf you want to serve the website over HTTP on your machine, use\n**serve**, and set the HTTP port with **--port** (the default is TCP port: *8000*).\n\n```sh\niraty --port 9000 serve site\n```\n\n## Remote pinning\n\n*Remote pinning* is supported via the **--pin-remote** (or **--pr**) switch.\nSpecify the name of the remote pinning service registered on your go-ipfs node\nwith **-rps** (otherwise it will use the *default RPS* specified in the node's\nconfiguration):\n\n```sh\niraty -i --pin-remote run site\niraty --pr --rps=pinata2 ipfs-deploy site\n```\n\n## Publish to an IPNS key\n\nYou can also publish your website to an IPNS key (if you use **--ipns-name**\nit will lookup a key with that name and create it if necessary, if you use\n**--ipns-id** you need to pass the *Id* of an existing key):\n\n```sh\niraty --ipns-name=my-dwebsite ipfs-deploy site\niraty --ipns-id=k51qzi5uqu5dkdol6lzkg0q7jaiv2r252ir9t5z8xbheg6g4vzd6lk2ydibe5y ipfs-deploy site\n```\n\n## Multiple languages (i18n)\n\nIf you wish to produce a multi-language website, your *YAML* files should\ninclude the [ISO 639-1 language code](https://en.wikipedia.org/wiki/ISO_639-1)\nin the filename suffix. Examples:\n\n- index.**en**.yaml\n- photos.**es**.yaml\n- article.**pt**.yaml\n\nYou need to pass the languages list with **--langs** to specify which\nlanguages you want to support (a language selector is included).\n\n```sh\niraty --langs=en,fr,es,de run site\niraty --lang-default=fr --langs=en,fr run site\n```\n\nCheckout [the basic 18n example](https://gitlab.com/cipres/iraty/-/tree/master/examples/i18n).\n\n## Restoring a config\n\n*iraty* caches the configuration for your site in a file called **.iraty.yaml**.\nTo reuse the last saved configuration, use **-r** or **--restore** (all\nother config arguments will be ignored):\n\n```sh\niraty -r run site\niraty --restore serve site\n```\n\n## Passing a single file\n\nYou can also pass a file. Convert and print a document to stdout with:\n\n```sh\niraty run document.yaml\niraty -t sakura-dark run document.yaml\n```\n\nConvert and import a document to IPFS (the CID is printed on the console):\n\n```sh\niraty -i run document.yaml\niraty -i run document.yaml|ipfs cat\n```\n\nLayouts are supported, look at the *block* resolver's documentation below and\ncheckout [the layout example](https://gitlab.com/cipres/iraty/-/tree/master/examples/layout).\n\n# Docker\n\nThe only difference with Docker is that you have to create a volume (here we\ngenerate the site from *$HOME/site* to *$HOME/public*):\n\n```sh\nsudo docker run -v $HOME:/h -t registry.gitlab.com/cipres/iraty:latest iraty -o /h/public run /h/site\n```\n\n# Examples\n\nTake a look [at the examples](https://gitlab.com/cipres/iraty/-/tree/master/examples).\n\nA div with some markdown that includes an embedded IPFS file, with an image:\n\n```yaml\nbody:\n  div:\n  - p: |-\n      # Hello\n\n      File contents .. ${cat:QmeomffUNfmQy76CQGy9NdmqEnnHU9soCexBnGU3ezPHVH}\n\n  - p: |-\n      # h1\n\n      Second paragraph\n\n  - img:\n      _src: 'https://example.com/someimage.png'\n```\n\nTables:\n\n```yaml\n- table:\n  - tr:\n    - td: One\n    - td: Two\n  - tr:\n    - td: Three\n    - td: Four\n```\n\nLinks (the *_* key sets the inner text of the DOM node):\n\n```yaml\na:\n  _href: \"https://ipfs.io\"\n  _: \"IPFS is the distributed web\"\n```\n\nEmbedding a [jinja2 template](https://gitlab.com/cipres/iraty/-/tree/master/examples/jinja):\n\n```yaml\nbody:\n  # Jinja template from string (passing variables)\n  - jinja:\n      template: |-\n        \u003cdiv\u003e\n\n        {% for i in range(num) %}\n          \u003cp\u003eIteration: {{ i }}\u003c/p\u003e\n        {% endfor %}\n\n        \u003c/div\u003e\n      with:\n        num: 5\n```\n\nAn image in base64 from an external IPFS file. HTML tag attributes must\nstart with *_*:\n\n```yaml\nimg:\n  _src: 'data:image/png;base64, ${cat64:QmUEd5oBhJJmb6WZWc7aHrPpcgF8ELEvcxHo6q4M8uWY5Q}'\n```\n\n# Resolvers\n\n## block\n\nDeclares a block. This is used inside a layout file called **.layout.yaml**.\nThis allows you to define a general layout for your website and not\nhave to declare the document structure over and over again.\n\n**.layout.yaml**:\n\n```yaml\ndiv: ${block:b1}\n```\n\nYour templates can then declare the block that will be replaced inside\nthe layout.\n\n**section.yaml**:\n\n```yaml\nblock_b1:\n  p:\n    The contents of block *b1*\n```\n\n*Note*: There is no safe-check on whether a block has already been defined or\nnot. Only the first matching block will be substituted.\n\n## dtnow_iso\n\nReturns the current date and time.\n\n```yaml\np: Current date and time ${dtnow_iso:}\n```\n\n\n## cat\n\n*cat* returns the contents (as a string) of an IPFS file or web resource.\nThe first and only argument is an IPFS path, an IPFS CID, or an HTTP/HTTPs URL.\n\n```yaml\ncontent: ${cat:QmeomffUNfmQy76CQGy9NdmqEnnHU9soCexBnGU3ezPHVH}\n\ncontent: ${cat:https://gitlab.com/cipres/iraty/-/raw/master/README.md}\n```\n\n## cat64\n\n*cat64* returns the contents in base64 of an IPFS file or web resource.\nThe first and only argument is an IPFS path, an IPFS CID, or an HTTP/HTTPs URL.\n\n```yaml\ncontent: ${cat64:QmeomffUNfmQy76CQGy9NdmqEnnHU9soCexBnGU3ezPHVH}\n```\n\n## csum_hex\n\n*csum_hex* returns the checksum as an hexadecimal string for a given resource\nand hashing algorithm.\n\nThe first argument is the algorithm, the second argument is the resource URL.\nUse an algorithm from the following list:\n\n```python\n{'blake2s', 'sha3_224', 'sha512', 'blake2b', 'shake_256', 'sha256', 'sha1', 'sha3_256', 'md5', 'sha3_384', 'sha384', 'shake_128', 'sha3_512', 'sha224'}\n```\n\nExample:\n\n```yaml\np: ${csum_hex:sha512,ipfs://bafkreihszin3nr7ja7ig3l7enb7fph6oo2zx4tutw5qfaiw2kltmzqtp2i}\n```\n\n## include\n\n*include* allows you to embed another (yaml) template in the DOM. The\nspecified path is relative to the root directory being processed, or relative\nto the directory containing the processed file:\n\n```yaml\nhead: ${include:.head.yml}\n```\n\nThe structure of the *.head.yml* template will go inside the *head* DOM element.\nHowever if you don't want to use a subtag, and just need the specified template\nto be included *in situ*, just use the *.* operator:\n\n```yaml\n.: ${include:.head.yml}\n```\n\n## toc\n\n*toc* generates a *Table of contents* for the given *scope* (at the moment,\nonly the *.* scope is implemented) and *depth*.\n\nCheckout [the toc example](https://gitlab.com/cipres/iraty/-/tree/master/examples/toc).\n\n```yaml\n.: ${toc:.}\n.: ${toc:., 3, \"Table of contents (depth 3)\"}\n```\n\n## unixfs_ls\n\n*unixfs_ls* gets the contents of an IPFS UnixFS directory, and returns it\nas an HTML list (*ul*). The second argument is a regular expression to\nfilter files.\n\nCheckout [the unixfs example](https://gitlab.com/cipres/iraty/-/tree/master/examples/unixfs).\n\n```yaml\n.: ${unixfs_ls:/ipns/dist.ipfs.io, .html$}\n```\n\n# Name origin\n\nThis tool is named after the succulent French (Basque) cheese called *Ossau-Iraty*.\n\n# Donate\n\nYou can make a donation for this project\n[here at Liberapay](https://liberapay.com/galacteek).\n\n# Thanks\n\nA big thanks to everyone involved with [OmegaConf](https://github.com/omry/omegaconf).\nSeveral *classless* CSS stylesheets are included in the repository:\n\n- [classlesscss](https://github.com/emareg/classlesscss)\n- [sakura](https://github.com/oxalorg/sakura)\n- [MercuryCSS](https://github.com/wmeredith/MercuryCSS)\n- [water.css](https://github.com/kognise/water.css)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinnaculum%2Firaty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinnaculum%2Firaty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinnaculum%2Firaty/lists"}