Skip to content
Snippets Groups Projects
Select Git revision
  • 8.x-1.0-beta4
  • 2.0.x default
  • 8.x-1.x
  • 8.x-1.0-beta6
  • 2.0.0-beta1
  • 8.x-1.0-beta5
  • 8.x-1.0-beta3
  • 8.x-1.0-beta2
  • 8.x-1.0-beta1
9 results

readmehelp

  • Clone with SSH
  • Clone with HTTPS
    • chipway-drupal's avatar
    Issue #3005913 by chipway, Aanal.addweb: All dependencies must be prefixed
    Léon CROS authored and drugan committed
    d4393872
    History
    chipway-drupal's avatar d4393872
    History
    Name Last commit Last update
    css
    images
    src
    tests
    README.md
    composer.json
    readmehelp.info.yml
    readmehelp.install
    readmehelp.libraries.yml
    readmehelp.module
    readmehelp.routing.yml
    readmehelp.services.yml
    your_module.module.example
    README.md

    README Help module

    Allows automatically to display module's README file on the admin/help/your_module page. Provides markdown ↗️ text filter for creating text formats.

    Tip: you can see this file in your browser by clicking the admin/help# link at the right of the Admin toolbar and then the admin/help/readmehelp# link in the list.

    Forget about implementing hook_help() in your_module.module file. Just write a decent README file with all information required and see it looking almost the same both on the admin/help/your_module page as well in your text editor. No more hardly to read (and to write!) markup intermingled with an actual user help text. All that you need is just to add the readmehelp dependency in your_module.info.yml and spend a couple of minutes learning the basics of the markdown syntax:

    Usage

    Open your_module.info.yml file and make it dependent on the readmehelp module:

    name: Your Module
type: module
description: Does awesome things.
core: 8.x
dependencies:
  - readmehelp

    Then, if your_module is already installed on the site, just flush the caches. If it's not, then the readmehelp will be installed automatically along with your_module. That's it. You may skip further reading if you are already familiar with markdown syntax or your_module help does not require complex data compiling or multi-page help.

    Markdown special symbols

    The README Help module's markdown syntax is a subset of the Github Flavoured Markdown syntax. Whenever possible the module attempts to replicate the look and feel of a Github repository's README file. Still, you may notice differences in some places of the admin/help/readmehelp# or on the module's Github repository.

    The markdown "tag" special symbols:

    • The asterisk: *
    • The backtick: `
    • The dash: -
    • The underscore: _
    • The line leading hash: #
    • The line leading greater than symbol: >
    • The line leading two greater than symbols: >>
    • The line leading three and more symbols set: ___
    • The line leading three and more symbols set: ***
    • The line leading three and more symbols set: ---
    • The line leading three and more symbols set: ===
    • The markdown anchor: []()
    • The markdown image: ![]()
    • The markdown unordered list item: - ITEM
    • The markdown ordered list item: 1. ITEM

    If it is required to display markdown symbol as a regular character then the backslash should be prepended to a symbol: \SYMBOL.

    Bold and Italic Text

    **Bold**

    ...converted into:

    Bold

    __Bold__

    ...converted into:

    Bold

    *Italic*

    ...converted into:

    Italic

    _Italic_

    ...converted into:

    Italic

    Blockquote and Cite

    > My Blockquote

    ...converted into:

    My Blockquote

    >> My Cite

    ...converted into:

    My Cite

    Note that every blockquote or cite can be referenced directly both locally and
externally by using the clickable greater than (>) sign at the left of a
block.

    Lists

    - ITEM

    ...converted into:

    • ITEM

    1.\ ITEM

    ...converted into:

    1. ITEM

    Anchor

    Relative path:

    Notice hash (#) signs in the url.

    [admin/reports/dblog#](#0 "Reports")

    ...converted into:

    admin/reports/dblog#

    Note that on the github.com the link above will work just as a dummy link.

    Absolute path:

    [PHP](http://php.net "On Hover Title")

    ...converted into:

    PHP

    Note that any raw text url, like http://php.net will be converted into:

    http://php.net

    Image

    Relative Path:

    ![ALT Text](images/druplicon.png "On Hover Title")

    ...converted into:

    ALT Text

    Absolute Path:

    ![ALT Text](https://raw.githubusercontent.com/drugan/readmehelp/8.x-1.x/images/drupalcat.png "On Hover Title")

    ...converted into:

    ALT Text

    See origin of the above image: https://octodex.github.com/images/drupalcat.jpg

    Horisontal Rule

    Three or more undescores like:

    ___

    ...converted into:

    Three or more asterisks like:

    ***

    ...converted into:

    Three or more dashes like:

    ---

    ...converted into:

    Headings

    Every heading can be referenced directly both locally and externally by using the clickable hash (#) sign at the left of a heading.

    # H1

    Alternative H1
==============

    ## H2

    Alternative H2
------------ -

    ### H3

    #### H4

    ##### H5

    ###### H6

    Note that # H1 and Alternative H1 syntax can be used just once at the very beginning of the file. So, demoing this heading is not possible here.

    ...converted into:

    H2

    Alternative H2

    H3

    H4

    H5
    H6

    Allowed HTML tags

    Besides the markdown a restricted set of HTML tags can be used for building README Help files:

    • a
    • em
    • strong
    • cite
    • blockquote
    • code
    • ul
    • ol
    • li
    • dl
    • dt
    • dd
    • img
    • h1
    • h2
    • h3
    • h4
    • h5
    • h6
    • p
    • pre
    • hr
    • table
    • tr
    • td
    • div
    • span

    Also, HTML Entities and HTML comments are supported.

    Dynamic PHP Snippets

    To insert higlighted snippet of any existing on a Drupal site PHP file you need to construct a token like the following:

    @PHPFILE: modules/contrib/readmehelp/readmehelp.module LINE:26 PADD:7 :PHPFILE@

    ...or just:

    @PHPFILE: readmehelp.module LINE:26 PADD:7 :PHPFILE@

    The absolute or relative path to a file may be followed by a LINE number argument and PADD, which is the number of lines to add before and after the LINE (additionally highlighted with yellow color). Both arguments are optional. If no PADD is passed then the default 10 lines will be added. If no LINE is passed then a whole highlighted file will be returned. There is a replacement of the token above (on the github.com shown as a raw token):

    @PHPFILE: readmehelp.module LINE:26 PADD:7 :PHPFILE@

    Markdown Text Filter

    README Help module has its own filter/tips#readmehelp-filter which could be used for creating admin/config/content/formats#. So, users can implement easy to remember syntax for making their posts richer while not able to harm a site, whether intentionally or not.

    Note that no any of the external libraries are used by the filter.

    Advanced README Help

    There might be cases when you still need to implement hook_help() and at the same time leverage the power of the README Help module. To restore the default behaviour you need additionally to implement dummy your_module_readmehelp() which disables automatic rendering of your module's README file and instead calls the regular your_module_help().

    Copy the code from the snippet below, insert it into your_module.module file and edit for your needs.

    @PHPFILE: your_module.module.example LINE:33 PADD:33 :PHPFILE@

    Module author:
      Vlad Proshin (drugan)
  [proshins@gmail.com](proshins@gmail.com)
  [https://drupal.org/u/drugan](https://drupal.org/u/drugan)