{"id":19692191,"url":"https://github.com/getgrav/grav-plugin-archives","last_synced_at":"2025-04-29T09:31:23.842Z","repository":{"id":19997176,"uuid":"23264535","full_name":"getgrav/grav-plugin-archives","owner":"getgrav","description":"Grav Archives Plugin","archived":false,"fork":false,"pushed_at":"2024-05-16T15:59:56.000Z","size":118,"stargazers_count":8,"open_issues_count":14,"forks_count":12,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-04-19T07:43:32.714Z","etag":null,"topics":["archive","archives","grav","grav-plugin","taxonomy"],"latest_commit_sha":null,"homepage":"https://getgrav.org","language":"PHP","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/getgrav.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-23T19:36:05.000Z","updated_at":"2024-05-16T15:59:59.000Z","dependencies_parsed_at":"2024-11-11T19:12:35.861Z","dependency_job_id":"d0e8c0cb-8510-47f1-9a7e-df64e122cec5","html_url":"https://github.com/getgrav/grav-plugin-archives","commit_stats":{"total_commits":71,"total_committers":12,"mean_commits":5.916666666666667,"dds":0.295774647887324,"last_synced_commit":"00545e00dd9c6644359d64ca804f76d81630e150"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-archives","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-archives/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-archives/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-archives/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getgrav","download_url":"https://codeload.github.com/getgrav/grav-plugin-archives/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251160203,"owners_count":21545312,"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":["archive","archives","grav","grav-plugin","taxonomy"],"created_at":"2024-11-11T19:12:32.918Z","updated_at":"2025-04-29T09:31:23.817Z","avatar_url":"https://github.com/getgrav.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grav Archives Plugin\n\n`Archives` is a [Grav](http://github.com/getgrav/grav) plugin that automatically appends a `month_year` taxonomy to all pages. It then provides a `partials\\archives.html.twig` template which you can include in a blog sidebar, that then is able to create links that will display pages from that month/year.  This is a very handy feature to have for blogs.\n\n# Installation\n\nInstalling the Archives plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file. \n\n## GPM Installation (Preferred)\n\n![GPM Installation](assets/readme_1.png)\n\nThe simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line).  From the root of your Grav install type:\n\n    bin/gpm install archives\n\nThis will install the Archives plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/archives`.\n\n## Manual Installation\n\nTo install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `archives`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-archives) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).\n\nYou should now have all the plugin files under\n\n    /your/site/grav/user/plugins/archives\n\n\u003e\u003e NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) plugins, and a theme to be installed in order to operate.\n\n# Usage\n\nThe `archives` plugin comes with some sensible default configuration, that are pretty self-explanatory:\n\n# Config Defaults\n\n```\nenabled: true\nbuilt_in_css: true\ndate_display_format: 'F Y'\nshow_count: true\nlimit: 12\ntaxonomy_names:\n    month: archives_month\n    year: archives_year\n#Defaults\norder:\n    by: date\n    dir: desc\nfilters:\n    category: blog\nfilter_combinator: and\n#New Page-Specific Configurations\npage_specific_config:\n    -  route: '/blog'\n       order:\n           by: date\n           dir: desc\n       filters:\n           page@: '/blog'\n       filter_combinator: and\n```\n\nIf you need to change any value, then the best process is to copy the [archives.yaml](archives.yaml) file into your `users/config/plugins/` folder (create it if it doesn't exist), and then modify there.  This will override the default settings.\n\n## Filter Types\n\n#### category\n\nThe legacy approach is to provide a specific category taxonomy filter, or multiple categories:\n\n```\nfilters:\n    category 'blog-post'\n```\n\n#### taxonomy@\n\nYou can use sophisticated taxonomy filtering with the same mechanism as page taxonomy filtering:\n\n```\nfilters:\n    taxonomy@.tag: photography # taxonomy called tag is set to photography\n```\n\nor:\n\n```\nfilters:\n    taxonomy@: {tag: birds, category: blog}\t # taxonomy with tag=birds \u0026\u0026 category=blog\n```\n\n#### page@\n\nYou can reference a specific page's collection via the page@ filter:\n\n```\nfilters:\n    page@: '/blog' # Use the collection defined in the header of `/blog` page\n```\n\n#### self@\n\nYou can also list the current children, without having to search for a taxonomy term by using\n\n```\nfilters:\n    - self@ # use the children defined in the current page\n```\n\n# Template Override\n\nSomething you might want to do is to override the look and feel of the archives, and with Grav it is super easy.\n\nCopy the template file [templates/partials/archives.html.twig](templates/partials/archives.html.twig) into the `templates/partials` folder of your custom theme, and that is it.\n\n```\n/your/site/grav/user/themes/custom-theme/templates/partials/archives.html.twig\n```\n\nYou can now edit the override and tweak it however you prefer.\n\n# Archives by Year example\n\nThe default `archives_data` object will contain pages broken out into groupings based on the `date_display_format` which by default is `F Y`, for example (`May 2024`).  If you want to display the archives by the \"Year\" only, rather than \"Month Year\", you need to modify the `data_display_format` in the `archives.yaml` configuration file:\n\n```yaml\ndate_display_format: 'Y'\n```\nNow the data will be grouped by year only. \n\nNext, you will need to override and modify the `partials/archives.html.twig` file, or alternatively point to the new example `partials/archives-year.html.twig` file.  This is modified to use the following syntax:\n\n```twig\n\u003cul class=\"archives\"\u003e\n\n{% for year,items in archives_data %}\n    \u003cli\u003e\n    \t\u003ca href=\"{{ archives_url ?? base_url }}/{{ config.plugins.archives.taxonomy_names.year }}{{ config.system.param_sep }}{{ year|date(config.plugins.archives.taxonomy_values.year)|lower|e('url') }}\"\u003e\n        {% if archives_show_count %}\n        \u003cspan class=\"label\"\u003e{{ items|length }}\u003c/span\u003e\n        {% endif %}\n        \u003cspan class=\"archive_date\"\u003e{{ year }} \u003c/span\u003e\n        \u003c/a\u003e\n    \u003c/li\u003e\n{% endfor %}\n\u003c/ul\u003e\n```\n\nThis is very similar to the default `partials/archives.html.twig` with `month` changed to `year`.\n\n# Updating\n\nAs development for Archives continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating Archives is easy, and can be done through Grav's GPM system, as well as manually.\n\n## GPM Update (Preferred)\n\nThe simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:\n\n    bin/gpm update archives\n\nThis command will check your Grav install to see if your Archives plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.\n\n## Manual Update\n\nManually updating Archives is pretty simple. Here is what you will need to do to get this done:\n\n* Delete the `your/site/user/plugins/archives` directory.\n* Downalod the new version of the Archives plugin from either [GitHub](https://github.com/getgrav/grav-plugin-archives) or [GetGrav.org](http://getgrav.org/downloads/plugins#extras).\n* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `archives`.\n* Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing `bin/grav clear-cache`.\n\n\u003e Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgrav%2Fgrav-plugin-archives","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetgrav%2Fgrav-plugin-archives","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgrav%2Fgrav-plugin-archives/lists"}