From 3bfd4dedbb725f2b766fc029daec6fadae7ab2a8 Mon Sep 17 00:00:00 2001
From: Eric Brown <eric.brown@securesauce.dev>
Date: Fri, 19 Jul 2024 09:10:58 -0700
Subject: [PATCH] Pretty up the home index for the docs

* Make use of grids to display information in an easier-to-read format
* Convert man page rst into markdown and provide link to it
* The grid links to the getting started, CLI reference, rules, and license

Signed-off-by: Eric Brown <eric.brown@securesauce.dev>
---
 .pre-commit-config.yaml            |  2 +-
 docs/index.md                      | 38 +++++++++++++++++++++++---
 docs/man/{precli.rst => precli.md} | 43 +++++++++++++-----------------
 mkdocs.yml                         | 12 ++++++---
 4 files changed, 63 insertions(+), 32 deletions(-)
 rename docs/man/{precli.rst => precli.md} (77%)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 84aed4df..4a7c1e6e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,4 +1,4 @@
-exclude: ^(docs|tests)
+exclude: ^(docs|tests|mkdocs.yml)
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
diff --git a/docs/index.md b/docs/index.md
index c0f56b34..558fde09 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,7 +4,39 @@ Precli is the core library for the GitHub App Precaution. It also serves as
 a command line interface. Precli is a SAST that analyzes code for security
 vulnerabilities.
 
-## License
 
-`precli` is provided under the terms and conditions of the
-[Business Source License 1.1](https://github.com/securesauce/precli/blob/main/LICENSE)
+<div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+    ---
+
+    Install `precli` with `pip` and get up and running in minutes
+
+    [:octicons-arrow-right-24: Getting started](getting-started)
+
+-   :material-console:{ .lg .middle } __CLI Reference__
+
+    ---
+
+    Guide on usage of the command line
+
+    [:octicons-arrow-right-24: CLI Reference](man/precli)
+
+-   :material-ruler:{ .lg .middle } __Explore Rules__
+
+    ---
+
+    Explore the various rules used in the detection of vulnerabilities
+
+    [:octicons-arrow-right-24: Rules](rules)
+
+-   :material-scale-balance:{ .lg .middle } __Open Source, BSL__
+
+    ---
+
+    Precli is licensed under `Business Source License` and available on [GitHub](https://github.com/securesauce/precli)
+
+    [:octicons-arrow-right-24: License](https://github.com/securesauce/precli/blob/main/LICENSE)
+
+</div>
diff --git a/docs/man/precli.rst b/docs/man/precli.md
similarity index 77%
rename from docs/man/precli.rst
rename to docs/man/precli.md
index d9b39b43..d884c827 100644
--- a/docs/man/precli.rst
+++ b/docs/man/precli.md
@@ -1,26 +1,23 @@
-======
-precli
-======
+# precli
 
-SYNOPSIS
-========
+## SYNOPSIS
 
+```
 precli [-h] [-d] [-r] [--enable ENABLE] [--disable DISABLE] [--json] [--plain]
        [--markdown] [--gist] [-o OUTPUT] [--no-color] [-q] [--version]
        [targets ...]
+```
 
+## DESCRIPTION
 
-DESCRIPTION
-===========
-
-``precli`` is a tool designed to find security issues in code. It finds issues
+`precli` is a tool designed to find security issues in code. It finds issues
 such as injection, weak hashes, cleartext transmission of data, timing
 attacks, weak encryption, deserialization of untrusted data, improper
 certificate validation, and more.
 
-OPTIONS
-=======
+## OPTIONS
 
+```
   -h, --help            show this help message and exit
   -d, --debug           turn on debug mode
   -r, --recursive       find and process files in subdirectories
@@ -35,24 +32,24 @@ OPTIONS
   --no-color            do not display color in output
   -q, --quiet           quiet mode, display less output
   --version             show program's version number and exit
+```
 
-FILES
-=====
+## FILES
 
 .preignore
   file that specifies which files and directories can be ignored
 
-ENVIRONMENT VARIABLES
-=====================
+## ENVIRONMENT VARIABLES
 
 DEBUG
+
   Set to any value to enabling debug logging.
 
 GITHUB_TOKEN
-  Set to your GitHub token. This is required to use the ``--gist`` argument.
 
-EXAMPLES
-========
+  Set to your GitHub token. This is required to use the `--gist` argument.
+
+## EXAMPLES
 
 Example usage across a code tree::
 
@@ -63,12 +60,10 @@ run Precli with standard input::
 
     cat examples/imports.py | precli -
 
-REPORTING BUGS
-==============
+## REPORTING BUGS
 
-Report issues at the following link: https://github.com/securesauce/precli/issues
+Report issues at the following link: [https://github.com/securesauce/precli/issues](https://github.com/securesauce/precli/issues)
 
-SEE ALSO
-========
+## SEE ALSO
 
-pylint(1)
+`pylint(1)`
diff --git a/mkdocs.yml b/mkdocs.yml
index 7ece4087..63e6d206 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,10 +17,9 @@ plugins:
   - search
 
 nav:
-  - Home:
-    - index.md
-  - 'User Guide':
-    - getting-started.md
+  - Home: index.md
+  - getting-started.md
+  - 'CLI Reference': man/precli.md
   - Rules:
     - Rules: rules.md
 
@@ -34,3 +33,8 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg