Creating Macros for Markdown files

[lloydsargent]

Hi! I noticed that my article on creating macros for Markdown files was deleted.

Since this appropriately falls under the category of “customization” I’m a little puzzled as to why it was removed?

For those who are interested, a friend posted the information on her website.

https://feloneouscat.wordpress.com/2019/03/24/what-picocms-deleted-how-to-write-macros/

[PhrozenByte]

Unfortunately one can't provide reasoning or send notice (no personal messages on GitHub either) when deleting a wiki page on GitHub. I was hoping that you'll create a Issue.

The reason why I deleted your contribution is because it's a very inefficient and error-prone way to do something actually pretty basic. You could simply use YAML variables. Add the following to the YAML Front Matter of a .md file in your content dir:

---
title: This is one of my pages
image:
  src: assets/2018/IMG_4026.jpg
  text: Baby Nine-Banded Armadillo
---

You can then access this variable in one of your .twig Templates in your themes/my_theme dir using:

{% if meta.image %}
  <figure id="myImg" onmousedown="zoomImageClick(this)”>
    <img class="modal-content" alt="" src="{{ meta.image.src }}”>
    <figcaption>{{ meta.image.text }}</figcaption>
  </figure>
{% endif %}

[lloydsargent]

Well for one image, this works fine. For multiple, it’s pretty weak. To assure it is located in the proper location in the Markdown becomes seriously iffy.

My site, on one page may contain hundreds of images. Your solution pales in comparison.

My solution neatly tidys up the HTML in a YAML file.

As for efficiency, yes, it will win no awards. However, it solves a problem without dropping into PHP.

If the goal is to ONLY provide solutions that meet your criteria, fine. My solution sucks, but it works.

I felt I sufficiently explained that it would win no awards. It would indeed be error-prone should someone use [img] (in the same way the current system is error-prone should someone inadvertently type \<div> — your mileage may vary).

PicoCMS isn’t my project and you are free to delete things as you see fit (as I have been reminded). However, there are no rules or guidelines as to what may be submitted to the Wiki. As this solved my problem, I figured it might assist others.

I’m sorry it didn’t meet your criteria.

[PhrozenByte]

If you're going to add hundreds of images to a single page (I assume in the form of an image gallery), you really should implement it with "separation of concerns" in mind. "Separation of concerns" is a concept virtually any CMS utilizes: the contents of a page shouldn't affect the layout of this page and vice-versa, allowing you to use the same contents for multiple concerns (e.g. your normal website vs. RSS feeds vs. structured data).

So, for multiple images try this:

---
title: This is one of my pages
images:
  - src: assets/2018/IMG_4026.jpg
    text: Baby Nine-Banded Armadillo
  - src: assets/2018/IMG_4027.jpg
    text: Another Image
  - src: assets/2018/IMG_4028.jpg
    text: Yet Another Image
---

{% for image in meta.images %}
  <figure id="myImg" onmousedown="zoomImageClick(this)”>
    <img class="modal-content" alt="" src="{{ image.src }}”>
    <figcaption>{{ image.text }}</figcaption>
  </figure>
{% endfor %}

Anyway, in the website you provided you're rather implementing a basic lightbox. In this case you should probably simply utilize CSS classes. Just refer to this .md file:

---
title: This is one of my pages
---

This is some content

![Baby Nine-Banded Armadillo](assets/2018/IMG_4026.jpg) {.lightbox}

This is some more content

![Another Image](assets/2018/IMG_4027.jpg) {.lightbox}

Even more content

![A Image not shown in a lightbox](assets/2018/IMG_4028.jpg)

And the following JavaScript snippet (better put in a .js file; untested code):

<script type="text/javascript">
var lightboxImages = document.querySelectorAll('img.lightbox');
for (var i = 0, lightboxWrapper, lightboxCaption; i < lightboxImages.length; i++) {
  lightboxCaption = document.createElement('figcaption');
  lightboxCaption.textContent = lightboxImages[i].getAttribute('alt');

  lightboxWrapper = document.createElement('figure');
  lightboxImages[i].parentNode.insertBefore(lightboxWrapper, lightboxImages[i]);
  lightboxWrapper.appendChild(lightboxImages[i]);
  lightboxWrapper.appendChild(lightboxCaption);

  lightboxWrapper.addEventListener('mousedown', function (e) {
    zoomImageClick(e.currentTarget);
  });
}
</script>

The use of onmousedown HTML attributes is discouraged in general. No PHP necessary, just some Markdown, Twig and JavaScript :wink:

As I said before, I'm sorry that I couldn't provide any info about the deletion, but GitHub's wiki feature is very limited and far away from being a "real" wiki. We're mostly using Pico's wiki it to give word about 3rd-party plugins and themes, so distinct guidelines and rules are probably overkill.

It's the first time we had this situation and IMO it turned out to have best possible outcome: Now we do have an conversation about it, preserved in an Issue, discussing various possible solutions, allowing others to find it, read it and choose the solution they favour depending on their individual situation. This wouldn't have been possible on a static Wiki page. We use GitHub Issues for everything, even as some sort of an forum :smiley:

[lloydsargent]

This is where we differ. You see a little problem where a solution that can be made more complex. I was looking for a solution that was simple.

My reason for moving to PicoCMS was simplicity. I am the sole maintenance person to this website. That covers a large number of use cases. I may add a module to wrap up assets in a similar manner as pages.

Or not. To be honest, many times “good enough” is enough.

My solution isn’t the “wrong way” if it satisfies my needs. That is a very important concept. Making things MORE complex means more to forget (web maintenance isn’t my job).

There are more people who find website maintenance a chore. Macros met my need and simplified creation of the site. I suspect it will meet many other people’s needs.

[PhrozenByte]

I've never said your solution is the "wrong way" :wink: All solutions are on the table now, in the end it's your website, you can choose whatever solution you prefer.

[lloydsargent]

Okay, I’ve spent about four hours and learned that basics of PHP and decided to create a plugin to create a list of assets from the selected directory in the *.md files YAML section.

Next step is to change my stupidly simple (I should say simplistic) macros into something a little more intelligent and faster by processing it with PHP rather than Twig.

This is the plugin. Currently writing the .md file to explain how it works. https://github.com/lloydsargent/grabassets

[lloydsargent]

The macro plugin was trivial. Need a little more for cleanup and then I’ll publish it to GitHub. Nice thing about this is that it keeps the amount of JS down to a minimum.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in two days if no further activity occurs. Thank you for your contributions! :+1:

[lloydsargent]

Okay, got stuck actually doing work, but I finished the macro plugin. It’s pretty efficient compared to doing it in Twig. Feel free to add it to your list of plugins.

https://github.com/lloydsargent/MarkdownMacros

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in two days if no further activity occurs. Thank you for your contributions! :+1: