Update 3.x cheat sheet with details from 2.x cheat sheet

Makes sense.

@Chi I'm thinking about your comment on 💬 Cheat sheet: format_size fliter needs explanation Fixed :

I wonder if we put more details into the documentation would it be still correct to call it cheat sheet? AFK cheat sheet is a document for those who don't want to spend time on reading detailed documentation.

I'm not sure where the line is between cheat sheet and detailed documentation. I am sure that I always liked using the 2.x cheat sheet :) But I'm only one person.

I think the brief "what this thing does" sentences are appropriate for a cheat sheet, and approximately one code snippet example per thing (not a hard rule).

Possible alternatives to adding parameter details to the 3.x cheat sheet:

1. A second .md file with the same content as the cheat sheet, plus all the "accepted parameters" details.
2. Add docblocks in the code -- I'm picturing the docblocks in Migrate Plus plugin source code (example: dom_str_replace), and link to those from the cheat sheet.
3. ??

Or, just flesh out the cheat sheet like the 2.x version :)

Let's try the "flesh out" approach.

Cool, thanks!

I'm posting on Slack > #contribute with an offer to mentor anyone who wants help, and if there are no takers, I'll get into it myself.

(If you land on this issue organically and are a new contributor who'd like help working on this issue, you can find me on Drupal Slack > #contribute channel or DM me on Slack @alison.)

One more option is creating a detailed documentation on drupal.org site. Though, I am not sure if it would be better.
Here are some explanations on why the cheat sheet was moved to git. #3174273: Migrate documentation from drupal.org to Git →

Mmmmmmmmm good point. I think I like it in the code, especially given how nice it is to look at + make use of code snippets on a platform like GitLab versus Drupal.org?? -- I can see the merit of it being on Drupal docs, but I'm leaning toward keeping it in the code repo, unless someone else speaks up.

Assigning to myself for this week.

Progress made, not done yet. Few questions:

Question 1:
I ran into something I didn't expect -- inside the parameter description lists, I couldn't use ` marks to format text as "code" (regular code HTML tags worked, but not the backticks). In other words, the following does not work, in the cheat-sheet.md file:

  <dt>`$name`</dt>

The following does work: (imagine no "spaces" in the code tag) (I got tired of fighting with this editor to output the literal code tag inside the code snippet)

  <dt>< code >$name< /code ></dt>

Not the end of the world, but it made me wonder:
Is there a different way I should add parameter details in markdown, rather than the description lists as they're done in Drupal docs?

Question 2:
File URI - this bit:

Media fields are fully supported including OEmbed resources, in which case it will return the URL to the resource, ...

It should be "it will return the URI of the resource", correct? -- just wanted to gut-check it before changing.

Question 3:
File URL - the last section of this one, under this text: "It is also possible to extract file URL directly from an entity."

The code examples are:

{{ image|file_url }}
{{ media|file_url }}

Is the first example, {{ image|file_url }}, meant to demonstrate getting a file URL from an image file entity, or from a media entity that's a "media type called image"?

(Depending on your answer) I suggest adding a comment before each one, i.e.

{# On an image file entity: #}
{{ image|file_url }}
{# On a media entity: #}
{{ media|file_url }}

Question 4:
File URI and File URL: The 2.x cheat sheet section on File URI starts with "Returns a file URI string." -- thoughts/feelings on adding this to the 3.x version? (If yes, I'll also add to the File URL section, "Returns a file URL string.")

regular code HTML tags worked, but not the backticks

That's by design. Backticks are part of markdown which is not processed withing HTML tags, at least by GitHub/GitLab markdown parsers. You may try <q/> or <var/> tags instead.

It should be "it will return the URI of the resource"

Yes

{{ image|file_url }}

It extracts the URL from image entity type.

thoughts/feelings on adding this to the 3.x version?

Makes sense.