{"id":13790563,"url":"https://github.com/shafayetShafee/nameref","last_synced_at":"2025-05-12T09:32:51.754Z","repository":{"id":145217250,"uuid":"594185419","full_name":"shafayetShafee/nameref","owner":"shafayetShafee","description":"A Quarto filter extension that allows to use name (section name, fig-name or table-name) to refer to these instead of number for html and pdf output format","archived":false,"fork":false,"pushed_at":"2023-02-16T21:03:08.000Z","size":2793,"stargazers_count":19,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-18T05:38:12.447Z","etag":null,"topics":["quarto","quarto-extension","quarto-filter","quarto-pub","quartopub"],"latest_commit_sha":null,"homepage":"","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/shafayetShafee.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2023-01-27T19:56:28.000Z","updated_at":"2024-09-13T14:06:04.000Z","dependencies_parsed_at":"2024-01-05T23:51:58.742Z","dependency_job_id":null,"html_url":"https://github.com/shafayetShafee/nameref","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shafayetShafee%2Fnameref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shafayetShafee%2Fnameref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shafayetShafee%2Fnameref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shafayetShafee%2Fnameref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shafayetShafee","download_url":"https://codeload.github.com/shafayetShafee/nameref/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253709361,"owners_count":21951124,"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":["quarto","quarto-extension","quarto-filter","quarto-pub","quartopub"],"created_at":"2024-08-03T22:00:46.802Z","updated_at":"2025-05-12T09:32:49.472Z","avatar_url":"https://github.com/shafayetShafee.png","language":"Lua","funding_links":[],"categories":["Extensions"],"sub_categories":[],"readme":"# Nameref Extension For Quarto\n\nA Quarto filter extension that allows to refer to section (like what latex package [`\\nameref`](https://mirror.las.iastate.edu/tex-archive/macros/latex/contrib/hyperref/doc/nameref.pdf) does), figure, image using a text/name instead of section number or plain `Figure #` or `Table #`. This filter works for both format `html` and `pdf`.\n\n## Installing\n\n*Note that, it is [recommended](https://quarto.org/docs/extensions/) to use a quarto version at least 1.2 to work with extensions.*\n\n```bash\nquarto add shafayetShafee/nameref\n```\n\nThis will install the extension under the `_extensions` subdirectory.\nIf you're using version control, you will want to check in this directory.\n\n## Using\n\n### Refer to a section using the text of the section header\n\nTo refer to a section, add an identifier, suppose `#how`, to header and use `\\nameref{how}` to reference that section.\n\n```\n## Why Quarto is so great {#how}\n\nSee \\nameref{how}.\n```\n\nAnd in rendered document this looks like,\n\n![section-reference](images/section_nameref.png)\n\n### Refer to code chunk generated plot or table\n\nTo name refer a plot or table generated from table, use the chunk option `link-id` that works as identifier and `link-title` that works as the reference text.\n\n````\n```{r}\n#| link-id: fig1\n#| link-title: My Awesome plot\n\nplot(1:10)\n```\n\nSee \\nameref{fig1}.\n\n````\n\nwhich looks like,\n\n![](images/chunk_nameref.png)\n\n\nNote that, `nameref` does not interfere with [Quarto's way](https://quarto.org/docs/authoring/cross-references.html#overview) of cross-referencing. You can use `label` and `fig-cap` to refer to this plot in usual way.\n\n\n### Refer to image or table written in markdown syntax\n\nTo use `nameref` for [markdown images](https://quarto.org/docs/authoring/figures.html#figure-basics) or for [markdown tables](https://quarto.org/docs/authoring/tables.html#markdown-tables), wrap the image or table with [Divs](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) (`:::`) with class `link` and `link-id`, `link-title` attributes.\n\n````\n::: {.link link-id=\"fig2\" link-title=\"Scatter plot\"}\n\n![mpg ~ hp](images/mpg.png)\n\n:::\n\nSee \\nameref{fig2}.\n\n````\n\n````\n::: {.link link-id=\"tab2\" link-title=\"Markdown table\"}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A    | B    | C    |\n| E    | F    | G    |\n| A    | G    | G    |\n\n: My Caption {#tbl-tab2}\n\n:::\n\nSee \\nameref{tab2}.\n\n````\n\nAnd this looks like, \n\n![](images/md_nameref.png)\n\n\n## Demo\n\nHere is the source code for a example: [example.qmd](example.qmd), containing the above all examples together in one place and the [live demo](https://shafayetshafee.github.io/nameref/example.html) of the rendered document in HTML output format. Also to see how `nameref` looks like in pdf format, [download](https://github.com/shafayetShafee/nameref/raw/main/docs/example.pdf) the rendered pdf output of `example.qmd` file.\n\n## Numbered nameref\n\nIt is also possible to use section number, figure or table number with the named reference. \n\n### using section number with section nameref\n\nTo get numbered section nameref, we need to do couple of things.\n\n- Firstly, use Quarto option `number-sections: true`\n- Secondly, use the `quarto` filter before the `nameref` filter (so that `nameref` can use the section number generated by `quarto` filter).\n- Lastly, use `section-number: true` under option `nameref`.\n\n````\n---\ntitle: \"Using nameref\"\nnumber-sections: true\nfilters: \n  - quarto\n  - nameref\nnameref:\n  section-number: true\n---\n\n# Why Quarto is so great {#sec-stack}\n\nSee \\nameref{sec-stack}.\n\n\n## Why Quarto is so great {#how}\n\nSee \\nameref{how}.\n````\n\nand the rendered output is,\n\n![](images/numbered_section.png)\n\n\n### using figure and table number with nameref\n\nThis filter provides no direct support to do this. But you can try a naive approach by using `@fig-id \\nameref{id}` together :wink:.\n\n### Demo\n\n[View a live demo of numbered `nameref`](https://shafayetshafee.github.io/nameref/numbered_example_html.html) of the rendered document in HTML output format and the source code [numbered_example_html.qmd](numbered_example_html.qmd)\n\nAlso to see how numbered `nameref` looks like in pdf format, [download](https://github.com/shafayetShafee/nameref/raw/main/docs/numbered_example.pdf) the rendered pdf output of [numbered_example.qmd](numbered_example.qmd) file.\n\n\n## Limitations\n\nThis filter does not work across chapters of Book for now. It works within a chapter but does not across, that is, you can not `nameref` a section (or image/table) in one chapter from another chapter. This is because, as per my knowledge, quarto filter applies to each chapter qmd file separately and I do not know how to make it work for all chapter qmd files at once. So if anybody knows this, [please let me know](https://github.com/shafayetShafee/nameref/pulls).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FshafayetShafee%2Fnameref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FshafayetShafee%2Fnameref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FshafayetShafee%2Fnameref/lists"}