Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/getgrav/grav-plugin-archives

Grav Archives Plugin
https://github.com/getgrav/grav-plugin-archives

archive archives grav grav-plugin taxonomy

Last synced: about 2 months ago
JSON representation

Grav Archives Plugin

Awesome Lists containing this project

README 

        
# 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:

    [email protected]: 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



```



This is very similar to the default `partials/archives.html.twig` with `month` changed to `year`.



# Updating



As 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.



## GPM Update (Preferred)



The 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:



    bin/gpm update archives



This 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.



## Manual Update



Manually updating Archives is pretty simple. Here is what you will need to do to get this done:



* Delete the `your/site/user/plugins/archives` directory.

* 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).

* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `archives`.

* 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`.



> 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.