Cards: Add a method of specifying a non-default image size

[jon-harper]

I'm using card grids both as a "big link button" and for an image gallery (along with glightbox).

I've basically used your stylesheet and hand-rolled the pages. In my own included CSS file I have an nt-gallery class, as well as nt-gallery-image and nt-gallery-title (no text class). I copied and then tweaked the settings from your own CSS file:

.nt-card .nt-gallery-image {
    text-align: center;
    border-radius: 5px;
    background-position: center center;
    background-size: cover;
    background-repeat: no-repeat;
    min-height: 200px;
}

.nt-card .nt-gallery-image img {
    height:200px;
    margin-top:5px
}

.nt-card .nt-gallery-content {
    padding:.4rem
}

.nt-card .nt-gallery-title {
    text-align: center;
    /* font-weight: 400; */
    font-size: 0.9em;
    font-weight: 700;
    margin:4px 0 8px 0;
    line-height:20px
}

I'm using both side-by-side with good success:

You can see on top cards using nt-card-* and below the modified gallery version.

Proposal

I propose to add a variable to pass to the card() call with the desired image height. From there it could calculate min-height values to apply as well.

An alternative would be a card_gallery() function that applies slightly modified styles, as I have done.

By the way, thank you for this project. It's done wonders for my documentation.

[RobertoPrevato]

Hi @jon-harper Thank You for your kind words! I am open to add an option to control image height, I think it's a good idea.

I prefer the idea of having a dedicated option to the existing cards() method, rather than adding a new cards_gallery().

Just to clarify, are you recommending something like this? >

cards(img-height=n)  # supporting both int (meaning pixels) and string that can be any CSS value

and then having HTML generated with images having style="height=n"? I would useheightin this case, or support bothheightandmin-height` control. By the way, now that I think of it, I should add the option to configure a class for the cards control.

[jon-harper]

Roberto -

Glad to help and glad that you like the idea!

Your approach makes a lot of sense to me, particularly being able to pass ints or CSS strings to the existing cards method. Other custom CSS values could be passed, like text alignment...ooh, or even a CSS class.

With a class parameter, cards("something.json", css_class="jh-gallery") would delegate lots of boilerplate to my extra.css file and cleanup the markdown.

Hope this is helpful!

Edit: I was having my first cup of coffee when I replied. I think I might have restated exactly what you already said. 🤦‍♂️

[RobertoPrevato]

Hi @jon-harper, I finally opted for supporting defining a class for the cards element, if you install version 1.0.0 from PyPI, you will get this feature. :)

I didn´t add an option to control the height of images because I realized it would be ambiguous (does it refer to a CSS height applied with styles as we discussed, or does it refer to the height property of img?). Controlling styling using classes is not ambiguous.

I opted for a name like in React - since "class" is a keyword in Python, so class-name="example".

Sorry for taking 2 weeks to do this, but I dedicated time to my other projects and I applied some more improvements (e.g. adopting pyproject.toml).

[RobertoPrevato]

Reopening because I need to document this feature. I'll close this issue once the feature is documented.

[jon-harper]

No need to apologize! Thanks for implementing the feature!

On Tue, Dec 20, 2022, 4:37 PM Roberto Prevato @.***> wrote:

Reopening because I need to document this feature. I'll close this issue once the feature is documented.

— Reply to this email directly, view it on GitHub https://github.com/Neoteroi/mkdocs-plugins/issues/28#issuecomment-1360404987, or unsubscribe https://github.com/notifications/unsubscribe-auth/AC2NUY5GFUNVWEBQYXZMFDDWOIYK3ANCNFSM6AAAAAASQ5MZFA . You are receiving this because you were mentioned.Message ID: @.***>

[joseale2310]

Hi @jon-harper @RobertoPrevato. I really like the style of the cards! However, I am very lost when it comes to css, creating classes, etc. I was wondering a couple of things:

1. How could I define/modify two cards individually? In my webpage I would like to add an Authors section and a Collaborators section. The Authors is a rather small list, so a nice sized card is perfect. However, the Contributor section might contain a lot of people, so if I could make the cards for the contributor section smaller, it would be awesome! Maybe @jon-harper could tell me how did you do yours?
2. Another interesting thing that could be done is making the cards like a "gallery" so you can click on arrows on the right/left side of the section and browse thtough all of them.

Thank you very much!

[jon-harper]

1. How could I define/modify two cards individually? In my webpage I would like to add an Authors section and a Collaborators section. The Authors is a rather small list, so a nice sized card is perfect. However, the Contributor section might contain a lot of people, so if I could make the cards for the contributor section smaller, it would be awesome! Maybe @jon-harper could tell me how did you do yours?

With the changes @RobertoPrevato made, you can pass a custom class-name (e.g., "foo") for one of the sets of cards. In your CSS file you can make changes to its appearance by specifying the properties to change:

.foo {
    background-color: blue;
}

Another interesting thing that could be done is making the cards like a "gallery" so you can click on arrows on the right/left side of the section and browse thtough all of them.

Look into GLightBox. It offers that kind of functionality.

[joseale2310]

@jon-harper Thank you very much for the quick answer! I am afraid that it still goes a bit above my head. How do I pass the class-name to the cards when writing markdown?

I have something like this:

## Authors

[cards cols="3"(./docs/assets/cards/author_cards.yaml)]

## Overview
bla bla bla
.
.
.

## Contributors

[cards cols="6"(./docs/assets/cards/contributor_cards.yaml)]

I took a look at glightbox, but it is not really what I am looking for. Thanks for the suggestion!

[RobertoPrevato]

Hi @joseale2310 Sorry for replying late, and thank you for your interest in the library.

Markdown gets built into HTML, so you can still use CSS to style the result.

I prepared an example for you:

## Bigger

::cards:: cols=3 class_name="bigger"

- title: Zeus
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/001-zeus.png

- title: Athena
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/003-athena.png

- title: Poseidon
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/007-poseidon.png

- title: Artemis
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/021-artemis.png

- title: Ares
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/006-ares.png

- title: Nike
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/027-nike.png

::/cards::

## Smaller

<style>
    .smaller .nt-card .nt-card-image img {
        height: 60px;
    }

    .smaller .nt-card .nt-card-image {
        min-height: 60px;
    }
</style>

::cards:: cols=6 class_name="smaller"

- title: Zeus
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/001-zeus.png

- title: Athena
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/003-athena.png

- title: Poseidon
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/007-poseidon.png

- title: Artemis
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/021-artemis.png

- title: Ares
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/006-ares.png

- title: Nike
  content: Lorem ipsum dolor sit amet.
  image: ./img/icons/027-nike.png

::/cards::

Normally you put custom CSS rules in dedicated files, and then configure those files in mkdocs.yml using the extra_css feature (I recommend this):

extra_css:
  - example/your_css_file.css

But you could even embed style elements in your Markdown code like in my example above (I don´t recommend this, it's just to illustrate that it's possible).

I still have to document the class_name feature, in the last months I focused on my web framework.

And thanks @jon-harper for helping! ☀️

[joseale2310]

This is perfect! Thank you both so much!