{"id":17306908,"url":"https://github.com/riccardoporreca/rmdgallery","last_synced_at":"2025-04-14T13:40:43.284Z","repository":{"id":42191448,"uuid":"248095857","full_name":"riccardoporreca/rmdgallery","owner":"riccardoporreca","description":"R Markdown Website Gallery Generator","archived":false,"fork":false,"pushed_at":"2025-04-12T00:57:19.000Z","size":297,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T01:39:25.812Z","etag":null,"topics":["gallery","rmarkdown","website"],"latest_commit_sha":null,"homepage":"https://riccardoporreca.github.io/rmdgallery/","language":"R","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/riccardoporreca.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2020-03-17T23:41:41.000Z","updated_at":"2022-12-14T23:13:52.000Z","dependencies_parsed_at":"2023-02-18T12:45:59.455Z","dependency_job_id":"a4bf6787-b236-4ba9-8ed7-697910bdb1ae","html_url":"https://github.com/riccardoporreca/rmdgallery","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riccardoporreca%2Frmdgallery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riccardoporreca%2Frmdgallery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riccardoporreca%2Frmdgallery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riccardoporreca%2Frmdgallery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riccardoporreca","download_url":"https://codeload.github.com/riccardoporreca/rmdgallery/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248889821,"owners_count":21178302,"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":["gallery","rmarkdown","website"],"created_at":"2024-10-15T11:59:51.158Z","updated_at":"2025-04-14T13:40:42.506Z","avatar_url":"https://github.com/riccardoporreca.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# rmdgallery\n\n\u003c!-- badges: start --\u003e\n[![CI](https://github.com/riccardoporreca/rmdgallery/actions/workflows/ci.yaml/badge.svg)](https://github.com/riccardoporreca/rmdgallery/actions/workflows/ci.yaml)\n[![Codecov test coverage](https://codecov.io/gh/riccardoporreca/rmdgallery/branch/main/graph/badge.svg)](https://codecov.io/gh/riccardoporreca/rmdgallery?branch=main)\n\u003c!-- badges: end --\u003e\n\nThe goal of **rmdgallery** is to provide an R Markdown [site generator](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#custom-site-generators) that supports the inclusion of a gallery of (embedded) pages created in a dynamic way based on metadata in JSON or YAML format.\n\nAn example of using **rmdgallery** can can be found in the [rmd-gallery-example](https://github.com/riccardoporreca/rmd-gallery-example#readme) GitHub repository.\n\n\n## Installation\n\nYou can install the [latest released](https://github.com/riccardoporreca/rmdgallery/releases/latest) version of **rmdgallery** package from GitHub with:\n\n``` r\nremotes::install_github(\"riccardoporreca/rmdgallery\")\n```\n\nIf you have a website R project, you can define **rmdgallery** as a dependency in the `DESCRIPTION` file, with the corresponding entry in the `Remotes:` field (possibly specifying which release tag to use):\n```\nImports:\n  rmdgallery\nRemotes:\n  riccardoporreca/rmdgallery\n```\nSee e.g. [rmd-gallery-example](https://github.com/riccardoporreca/rmd-gallery-example/blob/master/DESCRIPTION).\n\nIf you want to use the development version of the package, it is available from the [`develop`](https://github.com/riccardoporreca/rmdgallery/tree/develop) branch `riccardoporreca/rmdgallery@develop`, which can be used with `remotes::install_github()`\n``` r\nremotes::install_github(\"riccardoporreca/rmdgallery@develop\")\n```\nor in the `Remotes:` field of the `DESCRIPTION` file.\n\n## Using rmdgallery\n\nThe provided `rmdgallery::gallery_site` function (or it alias `rmdgallery::gallery_site_generator`) can be used as [custom site generator](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#custom-site-generators) for rendering a [simple R Markdown website](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html) via `rmarkdown::render_site()`. As such it must be specified as `site:` field of `index.(R)md`\n\n``` yaml\n---\ntitle: \"My Website\"\nsite: rmdgallery::gallery_site\n---\n```\n\nBelow we describe how the **_metadata_** for multiple pages are defined and used to render pages based on alternative **_templates_**, and how specific site **_configuration_** is added to the standard `_site.yml` configuration file.\n\n\n### Page metadata and templates\n\nAt the core of **rmdgallery** are R Markdown templates for the pages to be included in the website, containing placeholders for metadata. The details behind how templates define and make use of metadata are covered in section ['Custom templates'](#custom-templates) below.\n\nThe specific metadata of each individual page are defined in JSON (`.json`) or YAML (`.yml`, `.yaml`) file(s) in the `meta` directory of the website project. For example, the following YAML (or an analogous JSON)\n``` yaml\nfoo: \n  title: Embed raw html content\n  menu_entry: HTML example\n  template: embed-html\n  content: \u003ch3\u003eHello Rmd Gallery\u003c/h3\u003e\n\nbar: \n  title: Embed content from an external URL\n  menu_entry: URL example\n  menu_icon: fa-gear\n  template: embed-url\n  content: https://example.com\n```\ndefines the metadata for pages rendered as `foo.html` and `bar.html` with the given page `title`, also adding the specified `menu_entry` to the [site navigation bar](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation). The entry for `bar.html` in the site navigation bar will also include the specified `menu_icon`.\n\nThe way metadata, especially the `content`, are used to produce the resulting page depends on the specified `template`. Templates might in general make use of additional specific metadata fields, which can also be used for additional content included in the custom site [configuration](#configuration-and-customization).\n\nThe predefined templates provided by **rmdgallery** are described next.\n\n#### `\"template\": \"embed-url\"`\n\nEmbed a page given its URL, using `\u003cifame src={{content}}\u003e`, where `{{content}}` is the embedded page URL specified as `content` in the metadata. In addition, an optional `css` field in the metadata allows to fine-tune the CSS style of the `\u003ciframe\u003e`. In particular, `height` can be useful for defining the height (in valid CSS units) of the embedded non-responsive content, as in the following JSON example:\n``` json\n{\n  \"foo\": {\n    \"title\": \"My Title\",\n    \"template\": \"embed-url\",\n    \"content\": \"https://bookdown.org/yihui/rmarkdown\",\n    \"css\": {\n      \"height\": \"80vh\"\n    }\n  }\n}\n```\n\n#### `\"template\": \"embed-html\"`\n\nEmbed the HTML code defined in the `content` field of the metadata. This can be used for cases where more complex, custom embedding code must be supplied (e.g. social media, videos)\n\n#### `\"template\": \"embed-script\"`\n\nEmbed based on JavaScript, using `\u003cscript src={{content}}\u003e`, where `{{content}}` is the URL of a `.js` script. This is a special case of `embed-html`, useful e.g. for embedding a GitHub [gist](https://help.github.com/en/github/writing-on-github/editing-and-sharing-content-with-gists).\n\n#### Page types\n\nAn alternative way to defining a `template` field in the metadata is to use a custom field (e.g., `my_type`) defining the page _type_, and associate its possible custom values to actual templates. This is achieved by defining the `type_field` (e.g., `type_field: my_type`) and the `type_template` list of value-to-template maps (e.g., `type_1: embed-url`) in the `gallery` configuration (see below), so that metadata specifying field `my_type: type_1` (e.g. in YAML format) would be rendered using the `embed-url` template.\n\nThis approach can be particularly useful for galleries with user-contributed pages and metadata, where context-specific types (e.g., `type: shiny`) would be more informative than the rather technical `template`.\n\n### Configuration and customization\n\nConfiguration and customization of the website specific to `rmdgallery::gallery_site_generator` are defined by adding a `gallery:` field to the standard `_site.yml` configuration file. The following example describes the available options:\n\n``` yaml\nname: \"my-website\"\nnavbar:\n  title: \"My Website\"\n  left:\n    - text: \"Home\"\n      href: index.html\ngallery:\n  meta_dir: \"meta\"\n  single_meta: false\n  order_by: [title, desc(another_field)]\n  template_dir: \"path/to/cutom/templates\"\n  type_field: my_type\n  type_template:\n    type_1: embed-url\n    type_2: embed-html\n  defaults:\n    template: embed-url\n  navbar:\n    left:\n      - text: \"Gallery\"\n        icon: fa-gear\n  include_before: _includes/before_gallery.html\n  include_after: _includes/after_gallery.R\n```\n\n- `meta_dir:` Optional name of the directory containing `.json`, `.yml` and `.yaml` metadata files. Defaults to `meta` if not specified.\n- `single_meta:` Optional `true` or `false` defining whether the files define metadata for individual pages, in which case e.g. a file `foo.json` would contain only the metadata for the `foo.html` page. Defaults to `false` if not specified.\n- `order_by`: Optional fields used to sort the list of metadata. Use `desc(\u003cfield\u003e)` for decreasing order. If missing, the default `page_name` is a field added by **rmdgallery** containing the name of the entry in the metadata list for each page.\n- `template_dir:` Optional location of additional custom templates.\n- `type_field:`, `type_template:` Optional fields defining custom page _types_ (see ['Page types'](#page-types) above).\n- `defaults:` Optional list of default values for unspecified metadata fields.\n- `navbar:` The gallery navigation menu to be included in the standard `navbar:` of `_site.yml`. The menu is populated with the `menu_entry` of each page from the metadata. Can be omitted if no such menu should be included.\n- `include_before:`, `include_after:` Optional path to files defining custom content included before and after the main `content`. Both are included for each page and may be defined in terms of fields from the metadata using `{{...}}`. Such placeholders are then processed using `glue::glue_data(meta)`, where `meta` is the list of metadata for a given page. This allows to use simple string replacements in raw HTML code, as in the following example of `_includes/before_gallery.html`\n  ``` html\n  \u003chr\u003einclude_before for {{title}}\u003chr/\u003e\n  ```\n  but also to define complete R expressions constructing HTML elements via [**htmltools**](https://cran.r-project.org/package=htmltools), as in the following `_includes/after_gallery.R`:\n  ``` r\n  {{htmltools::tagList(\n      htmltools::hr(), \"include_after for\", title, htmltools::hr()\n  )}}\n  ```\n\nYou can see the various elements of the configuration in action in the [rmd-gallery-example](https://github.com/riccardoporreca/rmd-gallery-example#readme) GitHub repository.\n\n### Site-relative paths\n\nPaths to additional files (e.g. to `source()` utilities), needed when evaluating `{{...}}` expressions based on page-specific metadata and at rendering time,\ncan be safely constructed as relative to the site source directory using function `site_path()`.\n\n### Custom templates\n\nBesides the templates provided with **rmdgallery** (described above), it is possible to define custom R Markdown templates. These are standard R Markdown documents (as you would normally include in a [simple R Markdown website](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html)), which however will be populated with specific page metadata using two mechanisms:\n\n- Similar to what described for `include_before:`, `include_after:` above, any expression `{{...}}` is evaluated via `glue::glue_data(meta)` by looking up values from the list of metadata extracted from the JSON and YAML file(s). For example, the placeholder `{{toupper(title)}}` will be replaced with the uppercase version of the `title:` entry in the metadata. Such elements can be placed anywhere in the R Markdown document (not necessarily a code chunk), and make use of [**htmltools**](https://cran.r-project.org/package=htmltools) (see again `include_before:`, `include_after:` from the `gallery:` configuration above).\n\n- When the template is rendered for a given page, the metadata are also passed as `params` list. As such, templates work like [parameterized reports](https://bookdown.org/yihui/rmarkdown/parameterized-reports.html) and the relevant metadata should be declared as `params:` in the YAML front matter, along with sensible defaults. Metadata defined in this way are then evaluated as e.g. `params$content` in R code chunks or via \u003ccode\u003e\\`r params$content\\`\u003c/code\u003e inline.\n\nThe two approaches can coexist, but keep in mind that rendering the template as parameterized report happens **after** evaluating `{{...}}` placeholders. Also note that `params` cannot be used in the YAML front matter, so you should only use `{{...}}` there, which is always the case with `title: {{title}}`.\n\nIn addition to the metadata in the JSON and YAML files, a `gallery_config` element with the content of `gallery:` from the `_site.yml` configuration is also available when processing the template. In particular, `gallery_config$include_before` and `gallery_config$include_after` are added with placeholder expressions already evaluated, and templates should explicitly make use them to include them in the rendered page content.\n\nFunction `rmdgallery::gallery_content()` facilitates the construction of the content in a standardized way and it usage is recommended. In particular, it handles `gallery_config$include_before` and `gallery_config$include_after` and provides a common set of classed HTML elements (see below).\n\nThe templates provided within the package can be seen under 'inst/templates' in the source package, and are available at `system.file(\"templates\", package = \"rmdgallery\")` for the installed package.\n\n### CSS customization\n\nThe content of gallery pages constructed using the provided templates (or any custom template making use of `rmdgallery::gallery_content()`) have the following general structure (see also `?rmdgallery::gallery_content`)\n``` html\n\u003cdiv class=\"gallery-container {template/metadata-specific classes}\"\u003e\n  \u003cdiv class=\"gallery-before\"\u003e{include_before}\u003c/div\u003e\n  \u003cdiv class=\"gallery-main\"\u003e{main content}\u003c/div\u003e\n  \u003cdiv class=\"gallery-before\"\u003e{include_after}\u003c/div\u003e\n\u003c/div\u003e\n```\nwhich provide a convenient basis for styling the elements using CSS selectors.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friccardoporreca%2Frmdgallery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friccardoporreca%2Frmdgallery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friccardoporreca%2Frmdgallery/lists"}