Improve CONTRIBUTING

.github/CONTRIBUTING.md

@@ -12,14 +12,20 @@ Here are a few useul information for you:
 3. **Development**
     - Please create your own branch out of `master` and use it for you development and PR
     - Ensure you are basing your PR on the `master` branch and keep rebasing it on `master` when it changes
-    - You can have a decent development environment already setup by just using one of the apps in
-    the [Pagy Playground](https://ddnexus.github.io/pagy/playground) and/or
-    with the [Pagy::Console](https://ddnexus.github.io/pagy/docs/api/console/) directly from the repo
-4. **Testing**
-    - If your PR **does not add any new feature** (e.g. a fix), please, just ensure that the "All checks have passed" indicator
-    gets green light on the PR page (if it's not enabled, a maintainer will enable it for you)
-    - If your PR **adds new features**, it needs [Ruby testing](https://github.com/ddnexus/pagy/tree/master/test) and/or 
-      [E2E testing](https://github.com/ddnexus/pagy/tree/master/e2e) or the coverage will fail. Ask for support if you need 
+    - **Code**
+       - You can have a decent development environment already setup by just using one of the apps in
+      the [Pagy Playground](https://ddnexus.github.io/pagy/playground) and/or
+      with the [Pagy::Console](https://ddnexus.github.io/pagy/docs/api/console/) directly from the repo
+    - **Docs**
+      - `cd` in the pagy root directory
+      - Run `npm -i` or (`pnpm -i` if pnpm is installed). 
+      - Run `retype start`
+      - Point your browser at `http://localhost:5000/pagy` for real-time feedback
+5. **Testing**
+    - If your PR **does not add any new feature** (e.g. a fix), please, just ensure that the "All checks have passed" indicator gets
+      green light on the PR page (if it's not enabled, a maintainer will enable it for you)
+    - If your PR **adds new features**, it needs [Ruby testing](https://github.com/ddnexus/pagy/tree/master/test) and/or
+      [E2E testing](https://github.com/ddnexus/pagy/tree/master/e2e) or the coverage will fail. Ask for support if you need
       assistance.
 
 Thank you!

.github/workflows/publish-docs.yml

@@ -30,6 +30,9 @@ jobs:
             "README.yml",
             "retype.yml"
             ]'
+          paths_ignore: '[
+            "docs/README.md"
+            ]'
           do_not_skip: '["workflow_dispatch"]'
 
   publish:

docs/README.md

@@ -1,24 +1,11 @@
-### Documentation Contributions
+### How documenation works
 
-Documentation contributions or suggestions are welcome.
+The docs are written in [markdown format](https://en.wikipedia.org/wiki/Markdown) and [retype](https://retype.com/) converts it
+into styled HTML.
 
-1. Download [`retype`](https://retype.com/guides/cli/)
-2. `retype start` in the pagy root directory.
-
-And your docs should appear in a browser.
-
-#### Primer on how Pagy's Documentation works
-
-Pagy's documentation is built on [retype](https://retype.com/).
-
-All of [retype's configuration](https://retype.com/configuration/project/) is located in the [`retype.yml` file](https://github.com/ddnexus/pagy/blob/master/retype.yml). 
-
-Pagy uses a [github action](https://github.com/ddnexus/pagy/blob/master/.github/workflows/retype-action.yml) to trigger the build process i.e. the docs need to be "built". Why? Because the docs are written in [markdown format](https://en.wikipedia.org/wiki/Markdown) - however, markdown is not sufficient to deliver html to your browser. Retype does the hard work of converting that markdown into html with styling.
-
-Once built, then [Github pages](https://pages.github.com/) delivers it to you. But we must tell Github to deliver the html that has been created. Where is the html located? The html - i.e. the "built" site - is located in the root directory of the [`docs-site` branch](https://github.com/ddnexus/pagy/tree/docs-site) of the Pagy repository. The admin of the repository can set the branch that is used in the settings section of the repository.
-
-More details on the docs are available on the [retype website](https://retype.com/guides/github-actions/). 
-
-The Pagy repository is using the Open Source version, subject to certain limitations (i.e. total page count). [Pro version](https://retype.com/pro/) opens up other benefits. Credit to: [Retypeapp](https://github.com/retypeapp) and 
-[@geoffreymcgill](https://github.com/geoffreymcgill) and possibly others behind the scenes.
+The [retype configuration](https://retype.com/configuration/project/) is located in
+the [`retype.yml` file](https://github.com/ddnexus/pagy/blob/master/retype.yml).
 
+The [publish-docs workflow](https://github.com/ddnexus/pagy/blob/master/.github/workflows/publish-docs.yml) builds and
+publishes the documentation in the [`docs-site` branch](https://github.com/ddnexus/pagy/tree/docs-site) when its markdown changes
+are pushed to the `master` branch.