# Grav Archives Plugin `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. # Installation Installing 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. ## GPM Installation (Preferred) ![GPM Installation](assets/readme_1.png) The 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: bin/gpm install archives This will install the Archives plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/archives`. ## Manual Installation To 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). You should now have all the plugin files under /your/site/grav/user/plugins/archives >> 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. # Usage The `archives` plugin comes with some sensible default configuration, that are pretty self-explanatory: # Config Defaults ``` enabled: true built_in_css: true date_display_format: 'F Y' show_count: true limit: 12 taxonomy_names: month: archives_month year: archives_year #Defaults order: by: date dir: desc filters: category: blog filter_combinator: and #New Page-Specific Configurations page_specific_config: - route: '/blog' order: by: date dir: desc filters: page@: '/blog' filter_combinator: and ``` If 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. ## Filter Types #### category The legacy approach is to provide a specific category taxonomy filter, or multiple categories: ``` filters: category 'blog-post' ``` #### taxonomy@ You can use sophisticated taxonomy filtering with the same mechanism as page taxonomy filtering: ``` filters: taxonomy@.tag: photography # taxonomy called tag is set to photography ``` or: ``` filters: taxonomy@: {tag: birds, category: blog} # taxonomy with tag=birds && category=blog ``` #### page@ You can reference a specific page's collection via the page@ filter: ``` filters: page@: '/blog' # Use the collection defined in the header of `/blog` page ``` #### self@ You can also list the current children, without having to search for a taxonomy term by using ``` filters: - self@ # use the children defined in the current page ``` # Template Override Something you might want to do is to override the look and feel of the archives, and with Grav it is super easy. Copy 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. ``` /your/site/grav/user/themes/custom-theme/templates/partials/archives.html.twig ``` You can now edit the override and tweak it however you prefer. # Archives by Year example The 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: ```yaml date_display_format: 'Y' ``` Now the data will be grouped by year only. Next, 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: ```twig