We could be using README.md instead of README.txt to make use of the nicer rendering via markdown.

Now that we've moved to GitLab, we should probably use Markdown instead of plain .txt files for our documentation

Follow the pattern in the README.md template.

CommentFileSizeAuthor
#17 1.png765.28 KBrenatog
#14 how_to_section.jpg72.04 KBnagy.balint
#12 readme_format.jpg106.51 KBnagy.balint
Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

Jay Jangid created an issue. See original summary.

jay jangid’s picture

Assigned: jay jangid » Unassigned
Status: Active » Needs review

Created MR , please review.

Thank you.

nagy.balint made their first commit to this issue’s fork.

nagy.balint’s picture

Status: Needs review » Fixed

Thanks!

renatog’s picture

Status: Fixed » Needs work

Looking for the README.md template documentation: https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or...

I'm seeing some errors of the standards

1) Table of contents:
This one is the first one in the README.md file, and after that there is an "Introduction" with the description. For example in the Search API README that is used as example in the documentation: https://git.drupalcode.org/project/search_api/-/raw/8.x-1.x/README.md

2) Requirements
When there is no requirement the documentations says that the text should be

## Requirements

This module requires no modules outside of Drupal core.

3) How to use
As mentioned at #3335089-7: hook_help function missing in .module file this part is optional but I think can be useful an example about "how to use" to help the CMS editors

renatog’s picture

'

renatog’s picture

Status: Needs work » Needs review

'

renatog’s picture

nagy.balint’s picture

StatusFileSize
new106.51 KB

Actually I think, the previous is the correct order, see attached image.

renatog’s picture

Actually I think, the previous is the correct order, see attached image.

Yeah, you are right, good catch

I'll send a comment in the documentation explaining that, that the README linked as "example" is using an different order than have in the documentation and it can confuse the users reading the doc instead of helping

I just updated the MR, keeping this order as was before and I'm just including the "How to use" steps to help the users: https://git.drupalcode.org/project/email_contact/-/merge_requests/11

Thank you so much

nagy.balint’s picture

StatusFileSize
new72.04 KB

Hi!

There seem to be some issues in the patch. There are multiple 1s.

Attached image.

jay jangid’s picture

Thanks @nagy.balint for notify me.
Fixed issue , please review.

renatog’s picture

Status: Needs review » Reviewed & tested by the community

The fix seems good for me. Thanks @jay-jangid

renatog’s picture

Issue summary: View changes
StatusFileSize
new765.28 KB

@nagy.balint just to let you know, this is the syntax for Markdown with "numbered lists" you know?

Look that on this online editor https://markdownlivepreview.com/
In the left space paste this code:

## HOW TO USE

Since there are no extra settings, so to see that working you can follow these
steps:

1. Add the `"email"` field anywhere you want, for example: `"Basic Page"`
1. Go to Manage Display at:
   Configuration » Structure » Content types » < CONTENT-TYPE > Manage display
1. In the `"Format"` column you will see new options, for example:
    1. Email contact inline
    1. Email contact link
1. You can save that and see it working in the front-end

The resul will be with the correct ordinal numbers

Example on screenshot:

As I can see the MD syntax support both

1. item
1. item
1. item

and

1. item
2. item
3. item

Both will render as ordinal in the FE

Honestly I think the first one is better because if we have a lot of items, we don't need to put all of them following the order, 1,2,3,4 etc

Just put 1,1,1,1 the MK will apply that automatically in the FE

But since in our case we have just few items I think this last update on MR is also working fine, so for this reason I put as RTBC

  • nagy.balint committed d9ba77e5 on 2.x authored by RenatoG
    Issue #3335082 by RenatoG, Jay Jangid, nagy.balint: Added How To Use to...
nagy.balint’s picture

Status: Reviewed & tested by the community » Fixed

Thanks! I'm not using markdown often.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.