[FR] Improve README - confusing for new users

[ianrandmckenzie]

Hi there, as a new Obsidian user, the "Example Syntax" section was extremely confusing for me. If it weren't for my software background, I would have given up and uninstalled. Which would be silly because this plugin rocks.

The syntax block assumes people already know how this syntax stuff works and will immediately know what to do with that text. I think the README needs more explicit instructions on how to use this "Example Syntax"

[zenus260]

I agree. As a new user with rather limited coding experience, I'm at a loss which is a shame because the plugin seems really cool and does a lot of things I'm looking for.

[Welding-Torch]

We could start with some really simple instructions like:

1. Make a new note
2. In that note, paste the following

   ```note-gallery

3. That's it! Congratulations

[Welding-Torch]

And then follow it up with examples like:

• If you want to only see a gallery of notes in the current folder and not the subfolders, then paste:

  ```note-gallery
  recursive: false

[pashashocky]

Back from holiday! @ianrandmckenzie thank you for the PR. @Welding-Torch @zenus260 thank you for the recs, will implement a little more clarity into the README.

you guys rock!

[ksdavidc]

Yes, more suggestions along this line:

~~~~note-gallery     #           default | options

missed this the first few times through, and it was a little unclear, as we will see.

query: 'tag:#mytag'  # optional: anything you'd put into an obsidian search query

one question I have at this point is how to combine queries. should it be 'tag:#mytag' 'tag:#mytag2' or 'tag:#mytag tag:#mytag2' or do these have different meanings, etc.

                     # make sure to wrap into single quotes for any regex e.g.: '/\d/'
debugQuery: false    # optional: false | true - display native search results to debug

it should be made clear that you mean that false is the default (but see below) In general you should distinguish between what is a default option (aka what applies when this option is omitted entirely) and what is an example option. For example:

path: atlas          # optional: current note folder | path/to/folder - you don't **need**
                     # to use path if you are using query, path will source additional notes

here it is unclear what the default setting is. Is "atlas" the default? Should it be the words "current note folder", or is the current note folder the default? and if so is there an option to force the current folder, as Dataview does with "[[]]", and can we use it to single out subfolders.

off the top of my head, I imagine something like this, for example:

path: example/path/to/folder #(optional) expects: path, with or without quotes. options: path separated by slashes or dots | quoted path if path has spaces. default(if omitted): current folder. description/notes: this is *appended* to results from query, not included in the query itself. (or whatever is the case https://github.com/pashashocky/obsidian-note-gallery/issues/50#issue-2692831233)

generally:
option: example #(optional or required) expects: (text, or boolean, or list). default: (default setting). options: (list | of | options). description: (additional explanations)

[ksdavidc]

furthermore, to echo OP, a text walkthrough with a variety of examples would help a lot, not even just for newbies. Pros have particular questions and edge cases they want to understand.

Great plugin BTW