{"id":15789853,"url":"https://github.com/manunamz/jekyll-wikilinks","last_synced_at":"2025-04-15T21:24:46.118Z","repository":{"id":41171471,"uuid":"365254002","full_name":"manunamz/jekyll-wikilinks","owner":"manunamz","description":"Add [[wikilinks]] support for jekyll.","archived":false,"fork":false,"pushed_at":"2023-09-26T15:34:13.000Z","size":389,"stargazers_count":37,"open_issues_count":10,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-29T16:09:49.980Z","etag":null,"topics":["bidirectional-link","digital-garden","jekyll","net","network","web","wiki","wikilink"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/jekyll-wikilinks","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/manunamz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2021-05-07T14:08:23.000Z","updated_at":"2024-03-08T20:01:33.000Z","dependencies_parsed_at":"2024-10-04T22:04:02.560Z","dependency_job_id":"16f502d0-e77d-487f-a052-2c606b069bd6","html_url":"https://github.com/manunamz/jekyll-wikilinks","commit_stats":{"total_commits":327,"total_committers":6,"mean_commits":54.5,"dds":0.2262996941896025,"last_synced_commit":"e3270a8adc9d07a4de90550bd846dd3e2ca08b75"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manunamz%2Fjekyll-wikilinks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manunamz%2Fjekyll-wikilinks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manunamz%2Fjekyll-wikilinks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manunamz%2Fjekyll-wikilinks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manunamz","download_url":"https://codeload.github.com/manunamz/jekyll-wikilinks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249155534,"owners_count":21221620,"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":["bidirectional-link","digital-garden","jekyll","net","network","web","wiki","wikilink"],"created_at":"2024-10-04T22:03:59.042Z","updated_at":"2025-04-15T21:24:46.091Z","avatar_url":"https://github.com/manunamz.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jekyll-Wikilinks\n\n## ⚠️ As of v0.0.13, this plugin has moved to [`jekyll-wikirefs`](https://github.com/wikibonsai/jekyll-wikirefs)\n\nJekyll-Wikilinks adds wikilinking (the ability to reference local documents via the double square bracket syntax -- [[like this]]) support to jekyll -- and more.\n\nThis gem works in conjunction with [`jekyll-graph`](https://github.com/manunamz/jekyll-graph).\n\nThis gem is part of the [jekyll-bonsai](https://jekyll-bonsai.netlify.app/) project. 🎋\n\n## Installation\n\nFollow the instructions for installing a [jekyll plugin](https://jekyllrb.com/docs/plugins/installation/) for `jekyll-wikilinks`.\n\n## Configuration\n\nDefaults look like this:\n\n```yaml\nwikilinks:\n  attributes:\n    enabled: true\n  css:\n    exclude: []\n    name:\n      typed: 'typed'\n      wiki: 'wiki-link'\n      web: 'web-link'\n      invalid_wiki: 'invalid-wiki-link'\n      embed_container: 'embed-container'\n      embed_title: 'embed-title'\n      embed_content: 'embed-content'\n      embed_link: 'embed-wiki-link'\n      embed_image_container: 'embed-image-container'\n      embed_image: 'embed-image'\n  enabled: true\n  exclude: []\n```\n\n`attributes`: Toggles on/off attributes and block level wikilinks. If turned off the `attributes` meta data will not be added to each document and block level wikilinks will not be removed from the content of the document.\n\n`css_names`: Customiztable css class names.\n\n`css.exclude`: Defines a list of css classes that should not have the `wiki` or `web` css classes added to it.\n\n- This is useful when there are other internal links that should not have the `web-link` css class added to it. For example, `kramdown` adds `footnote` and `reversefootnote` css classes to `a` elements that are footnotes. Since they are links internal to the site, they won't have `wiki-link`s added to them, but it is likely undesirable to have `web-link` added to these elements. This makes them good candidates to exclude from the plugin's css processing altogether and style those classes separately.\n\n`enabled`: Toggle to turn off the plugin or turn off.\n\n`exclude`: Any jekyll type (`pages`, `posts`, or `collections` by name) may be added to a list of excluded documents to not be processed by the jekyll-wikilinks plugin.\n\n## Syntax\n\n### Inline Untyped File Level Wikilinks\n```markdown\n[[filename]]\n```\nThis link will match a markdown document anywhere in the jekyll project so long as it is named `filename.md`. Filenames must be unique, whitespace is allowed, and case is ignored.  The file's `title` frontmatter attribute is what gets rendered a the `a` tag's inner text.\n\nResulting HTML:\n```html\n\u003ca class=\"wiki-link\" href=\"url\"\u003elower-cased frontmatter title attribute\u003c/a\u003e\n```\n\n### Inline Typed File Level Wikilinks\n```markdown\nlink_type::[[filename]]\n```\nTypes should not contain whitespace. (kabob-case is recommended, but snake_case and camelCase will work too)\n\nThese wikilinks rendered in-place like untyped wikilinks. They also add a `typed` css class, as well as a css class with the name of the given link type.\n\nResulting HTML:\n```html\n\u003ca class=\"wiki-link typed link_type\" href=\"url\"\u003elower-cased frontmatter title attribute\u003c/a\u003e\n```\n\n### Block (Typed) Wikilinks\nAlso called a document's `attributes`, block wikilinks are typed wikilinks that are the only text on a single line:\n\n```\nlink_type::[[filename]]\n\nSome more text.\n```\n\nLists are also supported and may be defined by comma-separation or markdown lists (make sure bullet type matches for all items; e.g. all items use +'s, -'s or *'s):\n\n```\nlink_type::[[file-1]], [[file-2]], [[file-3]]\n\nlink_type::\n- [[file-1]]\n- [[file-2]]\n- [[file-3]]\n\nlink_type::\n+ [[file-1]]\n+ [[file-2]]\n+ [[file-3]]\n\nlink_type::\n* [[file-1]]\n* [[file-2]]\n* [[file-3]]\n```\n\nThese wikilinks are removed from the file entirely and their corresponding document urls and link types are saved in the `attributes` frontmatter variable of the current document and the `attributed` frontmatter variable of the linked documents.\n\nThe removal of these wikilink types is useful in the scenario where creating some form of infobox that is separate from the file's main content is desired.\n\nBlock wikilinks only work on the file-level and do not support labels or embedding. They may be toggled off in the configuration by setting: \n\n```\nwikilinks:\n  attributes: \n    enabled: false\n```\n\n---\n\n### Header Level Wikilinks\n```markdown\n[[filename#header]]\n```\nThis link will search for a file named `filename.md` and link to its `# header` if it has one. If no such header exists, the resulting `a` tag  will be rendered with the `invalid-wiki-link` css class.\n\nResulting HTML:\n```html\n\u003ca class=\"wiki-link\" href=\"url#sluggified-header-id\"\u003elower-cased frontmatter title \u003e header\u003c/a\u003e\n```\n\n### Block Level Wikilinks\n```markdown\n[[filename#^block_id]]\n```\n\nResulting HTML:\n```html\n\u003ca class=\"wiki-link\" href=\"url#block_id\"\u003elower-cased title \u003e ^block_id\u003c/a\u003e\n```\n- Make sure the ` ^block_id` in the target document has a space before the caret ` ^`.\n- CAVEAT:\n  - `^block_id`s themselves are left untouched so there is a way visually to identify the block once on the page's document.\n  - Blocks are treated the same way as headers, which is to say the `block_id` is appended as a url fragment (e.g. `www.blog.com/wikilink/#block_id`). With this url fragment, auto-scrolling to the corresponding html element id can be enabled. You will have to manually create those html elment ids yourself for now.\n\n---\n\n### File Paths \n⚠️ TODO: Unique filenames are still expected. This will change eventually.\n```markdown\n[[/directory/filename]]\n```\nFile paths may be added to a link to point to a file with more specificity.\n\n- Absolute paths should start with a forward slash `/`.\n- ⚠️ TODO: Relative paths should start with a directory name.\n\nFile paths only work for inline wikilinks.\n\nResulting HTML (this will look identical to wikilinks without file paths):\n```html\n\u003ca class=\"wiki-link\" href=\"url\"\u003efile's title\u003c/a\u003e\n```\n### Labels (sometimes called 'aliases')\n```markdown\n[[filename|label text]]\n```\nWhen using labels, the text that appears after the `|` will be rendered in the `a` tag's inner text instead of the document's `title` frontmatter.\n\nLabelling works for all wikilink levels (file, header, block).\n\nResulting HTML:\n```html\n\u003ca class=\"wiki-link\" href=\"url\"\u003elabel text\u003c/a\u003e\n```\n\n### Embeds\n```markdown\n![[filename]]\n```\nBy prepending `!` before a wikilink, the file's contents will be embedded in the current document rather than inserting just an `a` html tag.\n\nEmbeds only work for file-level wikilinks (not header or block).\n\nResulting HTML:\n```html\n\u003cdiv class=\"wiki-link-embed\"\u003e\n  \u003cdiv class=\"wiki-link-embed-title\"\u003e\n    // doc title here\n  \u003c/div\u003e\n  \u003cdiv class=\"wiki-link-embed-content\"\u003e\n    // embed content here\n  \u003c/div\u003e\n  \u003ca class=\"wiki-link-embed-link\" href=\"url\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n```\n\n### Embed Images\n```markdown\n![[image.png]]\n```\nLike the embeds above, link content will be rendered in the document body, but for images. Just be sure to add the file extension. Supported formats are `.png`, `.jpg`, `.gif`, `.psd`, `.svg`. Image wikilinks are not included in metadata.\n\nResulting HTML:\n```html\n\u003cp\u003e\n  \u003cspan class=\"wiki-link-embed-image\"\u003e\n    \u003cimg class=\"wiki-link-img\" src=\"img_relative_path\"/\u003e\n  \u003c/span\u003e\n\u003c/p\u003e\n```\n\nAn svg's content will be inserted directly into the html, rather than being linked in an `img` tag. This is useful in case you want to programmatically alter the svg post-render:\n\nResulting HTML:\n```html\n\u003cp\u003e\n  \u003cspan class=\"wiki-link-embed-image\"\u003e\n    \u003csvg\u003e\n      // svg file content here\n    \u003c/svg\u003e\n  \u003c/span\u003e\n\u003c/p\u003e\n```\n---\n\n### More Syntax\n\nFor more note-taking-related syntaxes such as \\=\\=highlights== and \\~\\~strikethroughs~~:\n\n- For kramdown, check out their [project page](https://github.com/gettalong/kramdown/projects/1) ([highlights ticket](https://github.com/gettalong/kramdown/issues/559), [strikethrough ticket](https://github.com/gettalong/kramdown/issues/594)).\n- For something that is functional now, see the [redcarpet markdown parser](https://github.com/vmg/redcarpet).\n\n\n## MetaData\nThe following metadata are stored as frontmatter variables and are accessible in liquid templates:\n\n- `attributed` (block backlinks)\n- `attributes` (block forelinks)\n- `backlinks`  (typed and untyped, file/header/block, back links)\n- `forelinks`  (typed and untyped, file/header/block, 'forward' links)\n- `missing`    (typed and untyped, file/header/block, forelinks that don't correspond to any document)\n\n### Block Wikilink (Attribute) Metadata\nThe `attributes` and `attributed` frontmatter variables, which correspond to block wikilinks, are lists of objects with a `type` attribute for the wikilink type and a list of `urls` which are strings:\n```yaml\n-\n  type: \u003cstr\u003e\n  urls: [\u003curl_str\u003e]\n-\n  ...\n```\nExample liquid:\n```html\n\u003c!-- render as 👉 \"link-type: title\" --\u003e\n\n{% for attr in page.attributed %}\n  {{ attr.type }}:\n  {% for url in attr.urls %}\n      {% assign linked_doc = site.documents | where: \"url\", attr.url | first %}\n      \u003ca class=\"wiki-link\" href=\"{{ linked_doc.url }}\"\u003e{{ linked_doc.title }}\u003c/a\u003e\n   {% endfor %}\n{% endfor %}\n```\n### Inline Wikilink Metadata\nThe `forelinks` and `backlinks` frontmatter variables, which correspond to inline wikilinks, is a list of objects with a `type` attribute for the wikilink type and a `url` string. (Untyped wikilinks will have an empty attribute: `type: \"\"`):\n\n```yaml\n-\n  type: \u003cstr\u003e\n  url: \u003curl_str\u003e\n-\n  ...\n```\nExample liquid:\n```html\n\u003c!-- render as 👉 \"link-type: title\" --\u003e\n\n{% for backlink in page.backlinks %}\n  {% assign linked_doc = site.documents | where: \"url\", backlink.url | first %}\n  {{ backlink.type }}: \u003ca class=\"wiki-link\" href=\"{{ linked_doc.url }}\"\u003e{{ linked_doc.title }}\u003c/a\u003e\n{% endfor %}\n```\n### Missing Metadata\n`missing` is simply a list of filenames. filenames for both block level and inline level wikilinks are collected:\n```yaml\n- \u003cfilename_str\u003e\n- ...\n```\n\n## Liquid Filters\n\nThere are two types of liquid filters provided: One for jekyll document types and one for link (relationship) types.\n\nSay you want to filter by jekyll document type. If you want to display 'post' backlinks and 'note' backlinks separately, just filter the backlinks metadata like so:\n\n```html\n\u003c!-- show post backlink titles --\u003e\n{% assign post_backlinks = page.backlinks | doc_type: \"posts\" %}\n{% for backlink in post_backlinks %}\n  {% assign post = site.posts | where: \"url\", backlink | first %}\n  {{ post.title }}\n{% endfor %}\n\n\u003c!-- show note backlink titles --\u003e\n{% assign note_backlinks = page.backlinks | doc_type: \"notes\" %}\n{% for backlink in note_backlinks %}\n  {% assign note = site.notes | where: \"url\", backlink | first %}\n  {{ note.title }}\n{% endfor %}\n```\n\nSay you want to filter by link (relationship) types. If you have markdown like the following:\n\n```markdown\nauthor::[[gardener]]\n```\n\nThen you could filter by the `author` type like so:\n\n```html\n{% assign author_links = page.links | link_type: \"author\" %}\n{% for link in author_links %}\n  {% assign post = site.posts | where: \"url\", link.url | first %}\n  {{ post.title }}\n{% endfor %}\n```\n\n## Some Other Implementations...\n\n### ...That Are Jekyll-Related\n- [A pure liquid impl](https://github.com/jhvanderschee/brackettest)\n- [A Jekyll Converter](https://github.com/metala/jekyll-wikilinks-plugin/blob/master/wikilinks.rb)\n- [Another Jekyll Converter](https://github.com/doitian/wikilink-converter)\n- [A template](https://github.com/maximevaillancourt/digital-garden-jekyll-template/blob/master/_plugins/bidirectional_links_generator.rb)\n\n### ...That Are Wiki-Related\n- [Gollum](https://github.com/gollum/gollum)\n- [Wikicloth](https://github.com/nricciar/wikicloth)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanunamz%2Fjekyll-wikilinks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanunamz%2Fjekyll-wikilinks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanunamz%2Fjekyll-wikilinks/lists"}