diff --git a/docs/Makefile.am b/docs/Makefile.am
index e11c42196..445d3fa2e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -37,7 +37,7 @@ EXTRA_DIST = MANUAL BUGS CONTRIBUTE.md FAQ FEATURES INTERNALS.md SSLCERTS.md \
  README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS      \
  KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY.md INSTALL        \
  $(PDFPAGES) LICENSE-MIXING README.netware INSTALL.devcpp               \
- MAIL-ETIQUETTE HTTP-COOKIES.md SECURITY RELEASE-PROCEDURE SSL-PROBLEMS \
+ MAIL-ETIQUETTE HTTP-COOKIES.md SECURITY.md RELEASE-PROCEDURE SSL-PROBLEMS.md \
  HTTP2.md ROADMAP.md CODE_OF_CONDUCT.md CODE_STYLE.md CHECKSRC.md
 
 MAN2HTML= roffit $< >$@
diff --git a/docs/SECURITY b/docs/SECURITY.md
similarity index 100%
rename from docs/SECURITY
rename to docs/SECURITY.md
diff --git a/docs/SSL-PROBLEMS b/docs/SSL-PROBLEMS.md
similarity index 95%
rename from docs/SSL-PROBLEMS
rename to docs/SSL-PROBLEMS.md
index e63987101..91803e22d 100644
--- a/docs/SSL-PROBLEMS
+++ b/docs/SSL-PROBLEMS.md
@@ -4,7 +4,7 @@
                             | (__| |_| |  _ <| |___
                              \___|\___/|_| \_\_____|
 
-SSL problems
+# SSL problems
 
   First, let's establish that we often refer to TLS and SSL interchangeably as
   SSL here. The current protocol is called TLS, it was called SSL a long time
@@ -14,19 +14,19 @@ SSL problems
   fail. This is a document that attempts to details the most common ones and
   how to mitigate them.
 
-CA certs
+## CA certs
 
   CA certs are used to digitally verify the server's certificate. You need a
   "ca bundle" for this. See lots of more details on this in the SSLCERTS
   document.
 
-CA bundle missing intermediate certificates
+## CA bundle missing intermediate certificates
 
   When using said CA bundle to verify a server cert, you will experience
   problems if your CA cert does not have the certificates for the
   intermediates in the whole trust chain.
 
-Protocol version
+## Protocol version
 
   Some broken servers fail to support the protocol negotiation properly that
   SSL servers are supposed to handle. This may cause the connection to fail
@@ -38,7 +38,7 @@ Protocol version
 
   All versions of SSL are considered insecure and should be avoided. Use TLS.
 
-Ciphers
+## Ciphers
 
   Clients give servers a list of ciphers to select from. If the list doesn't
   include any ciphers the server wants/can use, the connection handshake
@@ -61,7 +61,7 @@ Ciphers
 
   https://tools.ietf.org/html/draft-popov-tls-prohibiting-rc4-01
 
-Allow BEAST
+## Allow BEAST
 
   BEAST is the name of a TLS 1.0 attack that surfaced 2011. When adding means
   to mitigate this attack, it turned out that some broken servers out there in
@@ -72,7 +72,7 @@ Allow BEAST
   but on the other hand it allows curl to connect to that kind of strange
   servers.
 
-Disabling certificate revocation checks
+## Disabling certificate revocation checks
 
   Some SSL backends may do certificate revocation checks (CRL, OCSP, etc)
   depending on the OS or build configuration. The --ssl-no-revoke option was