docs: improve media_folder and public_folder docs

[erezrokah]

When https://www.netlifycms.org/docs/beta-features/#folder-collections-media-and-public-folder was introduced the main intended use case was to allow saving media files in the same folder as the entry under the constraint different entries don't share media files.
Since then we've added support for specifying per collection and per field media_folder and public_folder. We also allow media_folder to be either a relative path or an absolute path which can cause confusion: #3654 (comment).
We've also added templating and cascading for media_folder and public_folder which is not documented at all (#3670 (comment)).
We should document all of these changes and provide examples for each scenario.

Important

Make it clear to what the media_folder is used for (specifying where to save the file in the repo) and what public_folder is used for (specifying how to output the file path in the frontmatter).

[Undistraction]

@erezrokah Yep. This captures it. I think the best way to document this would be with examples as it is hard to model.

[theredwillow]

media_folder: /static/uploads/
public_folder: /uploads
collections:
  - name: posts
    label: Posts
    label_singular: 'Post'
    folder: src/content/posts
    create: true
    fields:
        - label: "Competition Logo"
          name: "complogo"
          widget: "image"
          media_folder: "{{media_folder}}/competitions"
          public_folder: "{{public_folder}}/competitions"
        - label: "Winner Image"
          name: "winnerimage"
          widget: "image"
          media_folder: "{{media_folder}}/winners"
          public_folder: "{{public_folder}}/winners"

Is this not working because I'm trying to assign media_folder's to individual fields? If not, I'd like to request this feature and would open an issue for it.

EDIT: Hmmm... Seems that moving it up to the main collection didn't make it work either, even after clearing the cache. Neither did using a relative path where I popped out from where the markdown was and into the static/img/competition folder.

I have no idea how to get this to work. Maybe it's because I manually added the image files to my repo? But if that was the case. wouldn't that also break when I added it to the main media_folder?? I've tried this on file and folder collections.

Another thing I noticed about images in Netlify/Gatsby is that where they are seems to matter inside the preview tool, but when you get to the actual pages, all the assets are mushed together. So if you have img/winners/2017/burger.jpg and img/winners/2018/burger.jpg, you will run into a problem of them both being named burger.jpg.

EDIT: I was pulling my hair out on this.

Setting the global level media_folder to static/img, resulting in images being saved (root) > static > img.

However, when I went into one of my fields and added media_folder: '{{media_folder}}/competitions', it actually saved it to src/pages/static/img/competitions/thisisatest.jpg (this is a relative path to the markdown).

So the collection and field media_folder paths are ALWAYS relative, even if your global one is not. The {{media_folder}} template tag doesn’t do anything but copy the string, which breaks paths because they start from different places. This is very confusing! As this issue documents, these docs need a serious overhaul.

[antoniohof]

up