#1059 (#1060)

* #1059

Author: jackdewinter

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,32 +7,64 @@ assignees: ''
 
 ---
 
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
-
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
-
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
-
-**Additional context**
-Add any other context about the problem here.
+## Prerequisites
+
+* [ ] Are you running the latest version of this application?
+* [ ] Have you checked the [Frequently Asked Questions](https://github.com/jackdewinter/pymarkdown/blob/main/docs/faq.md) document?
+* [ ] Have you simplified the bug report to the essential details?
+  * [ ] Do you have a distinct command line to report?
+  * [ ] Can you clearly state the configuration for this bug report?
+  * [ ] Do you have a minimal document that highlights this bug?
+  * [ ] Are any required files (configuration or Markdown document) attached to the issue?
+* [ ] Did you perform a cursory search of other issues to look for related issues?
+
+## Bug Report
+
+Please replace any of `[these areas]` in the paragraphs below with the requested information.
+
+### Bug Type
+
+* [ ] Assertion Failure
+* [ ] Documentation
+* [ ] Scan/Rule not working as expected
+* [ ] Fix/Rule not working as expected
+* [ ] Other
+  [Other reason]
+
+### Description
+
+[Provide a concise description of what the issue is.]
+
+### Specifics
+
+What operating system and version are you running into this behavior on?
+
+[Provide Operating System and Version Number]
+
+What version are you seeing this behavior in? (Run `pip list` or `pipenv run pip list` and look for the entry beside `pymarkdownlnt`.)
+
+[PyMarkdownLnt Version Number]
+
+Are there any extra steps that need to be taken before executing the application?
+
+[Any non-standard requirements?]
+
+What is the command line you invoke to get this behavior?
+
+[Assume that anything up to the first `pymarkdown` or `pymarkdownlnt` is already provided.]
+
+Are you using a configuration file? Either on the command line or one of the implicit configuration files? If so, attach that file to this issue.
+
+[Attach any configuration files that would alter processing behavior.]
+
+What Markdown document causes this behavior to manifest?  Attach that file to this issue.
+
+[Attach a minimal Markdown document that makes this behavior occur.]
+
+### Actual Behavior
+
+[Describe what behavior was seen when the specifics for executing the application were applied.]
+
+### Expected Behavior
+
+[Describe the behavior that you believe should occur instead of the Actual Behavior. Include any specifics on why that behavior is more correct.]

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,14 +7,24 @@ assignees: ''
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+## Prerequisites
 
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
+* [ ] Are you running the latest version of this application?
+* [ ] Have you checked the [Frequently Asked Questions](https://github.com/jackdewinter/pymarkdown/blob/main/docs/faq.md) document?
+* [ ] Did you perform a cursory search of other issues to look for related issues?
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
+## Feature Request
 
-**Additional context**
-Add any other context or screenshots about the feature request here.
+Please replace any of `[these areas]` in the paragraphs below with the requested information.
+
+### Description
+
+[Provide a concise description of what the requested feature is.]
+
+### Desired Behavior of Feature
+
+[Provide a clear picture of the feature you would like to see added, including specific scenarios or contexts where this feature would be particularly useful.  Markdown document samples, use cases, and other references will help you convey the necessity and impact your feature.]
+
+### What Are the Benefits of This Feature?
+
+[How many users do you believe will benefit from this feature?  How will it impact them?]

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ repos:
         entry: pipenv run python utils/correct_pdoc_issues.py
         pass_filenames: false
   - repo: https://github.com/jackdewinter/pymarkdown
-    rev: v0.9.11
+    rev: v0.9.18
     hooks:
       - id: pymarkdown
         pass_filenames: false
@@ -17,6 +17,16 @@ repos:
           - scan
           - .
           - ./docs
+  - repo: https://github.com/jackdewinter/pymarkdown
+    rev: v0.9.18
+    hooks:
+      - id: pymarkdown
+        pass_filenames: false
+        args:
+          - --config
+          - newdocs/clean.json
+          - scan
+          - ./newdocs/src
   - repo: local
     hooks:
       - id: verify-install-requirements

changelog.md

@@ -7,6 +7,8 @@
 - [Issue 801](https://github.com/jackdewinter/pymarkdown/issues/801)
   - Started movement of docs from README.md and docs directory to
     the newdocs directory with a shorter README.md.
+- [Issue 1059](https://github.com/jackdewinter/pymarkdown/issues/1059)
+  - Added updated pre-commit documentation.
 
 ### Fixed
 

newdocs/clean.json

@@ -1,18 +1,9 @@
 {
     "plugins": {
-        "no-space-in-code": {
-            "enabled": false
-        },
-        "no-space-in-emphasis": {
-            "enabled": false
-        },
         "line-length": {
-            "enabled": false,
+            "enabled": true,
             "code_block_line_length" : 160
         },
-        "no-duplicate-heading": {
-            "enabled": false
-        },
         "list-marker-space" : {
             "enabled": false
         },

newdocs/mkdocs.yml

@@ -12,10 +12,10 @@ nav:
     - 'getting-started.md'
   - "User Guide":
     - 'user-guide.md'
+    - 'advanced_configuration.md'
     - 'advanced_extensions.md'
     - 'advanced_plugins.md'
     - 'advanced_pre-commit.md'
-    - 'advanced_configuration.md'
   - "Devloper Guide":
     - 'api.md'
     - 'development.md'

newdocs/src/advanced_configuration.md

@@ -3,6 +3,12 @@
 This document will be the new home of the content currently located
 [here](https://github.com/jackdewinter/pymarkdown/blob/main/docs/advanced_configuration.md).
 
+## Configuration Files
+
+## Default Configuration Files
+
+## Different Types
+
 Other things that will be added:
 
 - config files
@@ -14,3 +20,61 @@ Other things that will be added:
 - [Command Line Settings](https://github.com/jackdewinter/pymarkdown/blob/main/docs/advanced_configuration.md#general-command-line-settings)
 - [Configuration File Settings](https://github.com/jackdewinter/pymarkdown/blob/main/docs/advanced_configuration.md#command-line-configuration-file)
 - [Available Configuration Values](https://github.com/jackdewinter/pymarkdown/blob/main/docs/advanced_configuration.md#available-configuration-values)
+
+### Command Line Configuration
+
+### Command Line Arguments Vs Configuration File
+
+The one question that comes up again and again, for PyMarkdown or for other projects,
+is whether to use a configuration file or command line arguments. And that answer
+largely relies on your context.  
+
+From our experience, there are typically five reasons for not using command line
+arguments for setting up your PyMarkdown hook in Pre-Commit:
+
+- conciseness: you prefer to keep any configuration values in a single file for
+  that application
+- reusability: you want to reuse those values in other locations, such as scripts
+- simplicity: you want to do more complicated configuration without specifying "extra"
+  command line options
+- single responsibility: you only want pre-commit hook configuration in the file,
+  everything else goes elsewhere
+- catch-all: because... personal taste
+
+If you are only leveraging the Pre-Commit hook for PyMarkdown and are not executing
+PyMarkdown from anywhere else in your project, many of the above reasons either may
+not apply or may not be as impactful to your decison.  There may also be other reasons
+not listed here, such as team guidelines, that sway the decision one way or the other.
+
+It really does come down to a team choice.  
+
+### Enabling or Disabling Rules
+
+As rules can be enabled or disabled on the command line, rules can also be enabled
+or disabled in the `.pre-commit-config.yaml` file.
+
+```yaml
+repos:
+    - repo: https://github.com/jackdewinter/pymarkdown
+      rev: main
+      hooks:
+          - id: pymarkdown
+            args:
+                - -d
+                - MD041,md013
+                - scan
+```
+
+Note that if presenting the arguments on a single line and there are multiple rules
+that are being enabled or disabled, the commma separated list must be enclosed in
+quotes.  The quote characters allow Pre-Commit to understand that the comma inside
+of the quotes is part of the data, not a character separating the data.
+
+```yaml
+repos:
+    - repo: https://github.com/jackdewinter/pymarkdown
+      rev: main
+      hooks:
+          - id: pymarkdown
+            args: [-d, "MD041,MD013", scan ]
+```