[Docs] Added linting for markdown files (#977)

* adding a note about required common bins (issue #973)

* added markdownlint policy

* applied markdownlint

* customized mdlint config

.editorconfig

@@ -21,4 +21,4 @@ indent_style = space
 indent_size = 2
 
 [*.md]
-max_line_length=100
+max_line_length = 100

docs/.markdownlint.yaml

@@ -0,0 +1,259 @@
+# Default state for all rules
+default: true
+
+# Path to configuration file to extend
+extends: null
+
+# MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time
+MD001: true
+
+# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading
+MD002:
+  # Heading level
+  level: 1
+
+# MD003/heading-style/header-style - Heading style
+MD003:
+  # Heading style
+  style: "consistent"
+
+# MD004/ul-style - Unordered list style
+MD004:
+  # List style
+  style: "consistent"
+
+# MD005/list-indent - Inconsistent indentation for list items at the same level
+MD005: true
+
+# MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line
+MD006: true
+
+# MD007/ul-indent - Unordered list indentation
+MD007:
+  # Spaces for indent
+  indent: 2
+  # Whether to indent the first level of the list
+  start_indented: false
+  # Spaces for first level indent (when start_indented is set)
+  start_indent: 2
+
+# MD009/no-trailing-spaces - Trailing spaces
+MD009:
+  # Spaces for line break
+  br_spaces: 2
+  # Allow spaces for empty lines in list items
+  list_item_empty_lines: false
+  # Include unnecessary breaks
+  strict: false
+
+# MD010/no-hard-tabs - Hard tabs
+MD010:
+  # Include code blocks
+  code_blocks: false
+  # Fenced code languages to ignore
+  ignore_code_languages: []
+  # Number of spaces for each hard tab
+  spaces_per_tab: 4
+
+# MD011/no-reversed-links - Reversed link syntax
+MD011: true
+
+# MD012/no-multiple-blanks - Multiple consecutive blank lines
+MD012:
+  # Consecutive blank lines
+  maximum: 2
+
+# MD013/line-length - Line length
+MD013:
+  # Number of characters
+  line_length: 100
+  # Number of characters for headings
+  heading_line_length: 100
+  # Number of characters for code blocks
+  code_block_line_length: 100
+  # Include code blocks
+  code_blocks: false
+  # Include tables
+  tables: false
+  # Include headings
+  headings: true
+  # Include headings
+  headers: true
+  # Strict length checking
+  strict: false
+  # Stern length checking
+  stern: false
+
+# MD014/commands-show-output - Dollar signs used before commands without showing output
+MD014: true
+
+# MD018/no-missing-space-atx - No space after hash on atx style heading
+MD018: true
+
+# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
+MD019: true
+
+# MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
+MD020: true
+
+# MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
+MD021: true
+
+# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
+MD022:
+  # Blank lines above heading
+  lines_above: 1
+  # Blank lines below heading
+  lines_below: 1
+
+# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
+MD023: true
+
+# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
+MD024:
+  # Only check sibling headings
+  allow_different_nesting: false
+  # Only check sibling headings
+  siblings_only: false
+
+# MD025/single-title/single-h1 - Multiple top-level headings in the same document
+MD025:
+  # Heading level
+  level: 1
+  # RegExp for matching title in front matter
+  front_matter_title: "^\\s*title\\s*[:=]"
+
+# MD026/no-trailing-punctuation - Trailing punctuation in heading
+MD026:
+  # Punctuation characters not allowed at end of headings
+  punctuation: ".,;:!。，；：！"
+
+# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
+MD027: true
+
+# MD028/no-blanks-blockquote - Blank line inside blockquote
+MD028: true
+
+# MD029/ol-prefix - Ordered list item prefix
+MD029:
+  # List style
+  style: "one_or_ordered"
+
+# MD030/list-marker-space - Spaces after list markers
+MD030:
+  # Spaces for single-line unordered list items
+  ul_single: 2
+  # Spaces for single-line ordered list items
+  ol_single: 2
+  # Spaces for multi-line unordered list items
+  ul_multi: 2
+  # Spaces for multi-line ordered list items
+  ol_multi: 2
+
+# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
+MD031:
+  # Include list items
+  list_items: true
+
+# MD032/blanks-around-lists - Lists should be surrounded by blank lines
+MD032: true
+
+# MD033/no-inline-html - Inline HTML
+MD033:
+  # Allowed elements
+  allowed_elements: []
+
+# MD034/no-bare-urls - Bare URL used
+MD034: true
+
+# MD035/hr-style - Horizontal rule style
+MD035:
+  # Horizontal rule style
+  style: "consistent"
+
+# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
+MD036:
+  # Punctuation characters
+  punctuation: ".,;:!?。，；：！？"
+
+# MD037/no-space-in-emphasis - Spaces inside emphasis markers
+MD037: true
+
+# MD038/no-space-in-code - Spaces inside code span elements
+MD038: true
+
+# MD039/no-space-in-links - Spaces inside link text
+MD039: true
+
+# MD040/fenced-code-language - Fenced code blocks should have a language specified
+MD040:
+  # List of languages
+  allowed_languages: []
+  # Require language only
+  language_only: false
+
+# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
+MD041:
+  # Heading level
+  level: 1
+  # RegExp for matching title in front matter
+  front_matter_title: "^\\s*title\\s*[:=]"
+
+# MD042/no-empty-links - No empty links
+MD042: true
+
+# MD043/required-headings/required-headers - Required heading structure
+MD043:
+  # List of headings
+  headings: []
+  # List of headings
+  headers: []
+  # Match case of headings
+  match_case: false
+
+# MD044/proper-names - Proper names should have the correct capitalization
+MD044:
+  # List of proper names
+  names: []
+  # Include code blocks
+  code_blocks: false
+  # Include HTML elements
+  html_elements: false
+
+# MD045/no-alt-text - Images should have alternate text (alt text)
+MD045: true
+
+# MD046/code-block-style - Code block style
+MD046:
+  # Block style
+  style: "consistent"
+
+# MD047/single-trailing-newline - Files should end with a single newline character
+MD047: true
+
+# MD048/code-fence-style - Code fence style
+MD048:
+  # Code fence style
+  style: "consistent"
+
+# MD049/emphasis-style - Emphasis style should be consistent
+MD049:
+  # Emphasis style should be consistent
+  style: "consistent"
+
+# MD050/strong-style - Strong style should be consistent
+MD050:
+  # Strong style should be consistent
+  style: "consistent"
+
+# MD051/link-fragments - Link fragments should be valid
+MD051: true
+
+# MD052/reference-links-images - Reference links and images should use a label that is defined
+MD052: true
+
+# MD053/link-image-reference-definitions - Link and image reference definitions should be needed
+MD053:
+  # Ignored definitions
+  ignored_definitions:
+    - "//"

docs/api.md

@@ -33,6 +33,7 @@ register_external_command(NewCommand())
 ```
 
 Loading it in `GEF` is as easy as
+
 ```
 gef➤  source /path/to/newcmd.py
 [+] Loading 'NewCommand'
@@ -61,15 +62,17 @@ We make GEF aware of this new command by registering it in the `__main__` sectio
 invoking the global function `register_external_command()`.
 
 Now you have a new GEF command which you can load, either from cli:
+
 ```bash
 gef➤  source /path/to/newcmd.py
 ```
+
 or add to your `~/.gdbinit`:
+
 ```bash
-$ echo source /path/to/newcmd.py >> ~/.gdbinit
+echo source /path/to/newcmd.py >> ~/.gdbinit
 ```
 
-
 ## Customizing context panes
 
 Sometimes you want something similar to a command to run on each break-like event and display itself
@@ -119,20 +122,22 @@ gef➤  pi help(Architecture)
 or even from outside GDB:
 
 ```bash
-$ gdb -q -ex 'pi help(hexdump)' -ex quit
+gdb -q -ex 'pi help(hexdump)' -ex quit
 ```
 
 The GEF API aims to provide a simpler and more Pythonic approach to GDB's.
 
 Some basic examples:
-- read the memory
-```python
+* read the memory
+
+```text
 gef ➤  pi print(hexdump( gef.memory.read(parse_address("$pc"), length=0x20 )))
 0x0000000000000000     f3 0f 1e fa 31 ed 49 89 d1 5e 48 89 e2 48 83 e4    ....1.I..^H..H..
 0x0000000000000010     f0 50 54 4c 8d 05 66 0d 01 00 48 8d 0d ef 0c 01    .PTL..f...H.....
 ```
 
-- get access to the memory layout
+* get access to the memory layout
+
 ```
 gef ➤ pi print('\n'.join([ f"{x.page_start:#x} -> {x.page_end:#x}" for x in gef.memory.maps]))
 0x555555554000 -> 0x555555558000
@@ -148,18 +153,15 @@ gef ➤ pi print('\n'.join([ f"{x.page_start:#x} -> {x.page_end:#x}" for x in ge
 [...]
 ```
 
-
 The API also offers a number of decorators to simplify the creation of new/existing commands, such as:
-- `@only_if_gdb_running` to execute only if a GDB session is running.
-- `@only_if_gdb_target_local` to check if the target is local i.e. not debugging using GDB `remote`.
-- and many more...
-
+* `@only_if_gdb_running` to execute only if a GDB session is running.
+* `@only_if_gdb_target_local` to check if the target is local i.e. not debugging using GDB `remote`.
+* and many more...
 
 ### Reference
 
 For a complete reference of the API offered by GEF, visit [`docs/api/gef.md`](api/gef.md).
 
-
 ### Parsing command arguments
 
 ```python
@@ -179,12 +181,10 @@ using a type of `tuple` or `list` for the default value. `parse_arguments` will
 of what to expect based on the first default value of the iterable, so make sure it's not empty. For
 instance:
 
-
 ```python
 @parse_arguments( {"instructions": ["nop", "int3", "hlt"], }, {"--arch": "x64", } )
 ```
 
-
 Argument flags are also supported, allowing to write simpler version of the flag such as
 
 ```python
@@ -227,11 +227,11 @@ Sometimes architectures can more precisely determine whether they apply to the c
 looking at the architecture determined by gdb. For these cases the custom architecture may implement
 the `supports_gdb_arch()` static function to signal that they should be used instead of the default.
 The function receives only one argument:
-- `gdb_str` (of type `str`) which is the architecture name as reported by GDB.
+* `gdb_str` (of type `str`) which is the architecture name as reported by GDB.
 
 The function **must** return:
-- `True` if the current `Architecture` class supports the target binary; `False` otherwise.
-- `None` to simply ignore this check and let GEF try to determine the architecture.
+* `True` if the current `Architecture` class supports the target binary; `False` otherwise.
+* `None` to simply ignore this check and let GEF try to determine the architecture.
 
 One example is the ARM Cortex-M architecture which in some cases should be used over the generic ARM
 one:

docs/commands/aslr.md

@@ -3,12 +3,14 @@
 Easily check, enable or disable ASLR on the debugged binary.
 
 Check the status:
+
 ```
 gef➤  aslr
 ASLR is currently disabled
 ```
 
 Activate ASLR:
+
 ```
 gef➤  aslr on
 [+] Enabling ASLR
@@ -17,6 +19,7 @@ ASLR is currently enabled
 ```
 
 De-activate ASLR:
+
 ```
 gef➤  aslr off
 [+] Disabling ASLR