title: Include my markdown README into Sphinx
body: <p>I would like to include my project's <code>README.md</code> into my Sphinx documentation like in
  <a href="https://stackoverflow.com/questions/10199233/can-sphinx-link-to-documents-that-are-not-located-in-directories-below-the-root">Can sphinx link to documents that are not located in directories below the root document?</a>
  - which is that in the resulting Sphinx html documentation I click on a link in the table of contents on the welcome page and get to the <code>README.md</code>.</p>
  
  <p>For that a document <code>readme_link.rst</code> is created which contains the lines</p>
  
  <pre><code>Readme File
  -----------
  
  .. include:: ../../README.md
  </code></pre>
  
  <p>and I add the line</p>
  
  <pre><code>README &lt;readme_link&gt;
  </code></pre>
  
  <p>into the toctree of <code>index.rst</code>.
  Going with that, my <code>README.md</code> is not parsed as Markdown, but just printed onto the page as-is-text.</p>
  
  <p>I thought an alternative idea might be to have a markdown file <code>readme_link.md</code> instead, but there is no way to include files with markdown.</p>
  
  <p><strong>How can I have my README.md parsed as markdown?</strong></p>
  
  <p>(Of course I don't want to rewrite it as .rst.)</p>
  
  <h2>Why <a href="https://github.com/miyakogi/m2r#sphinx-integration" rel="noreferrer">m2r</a> is not working</h2>
  
  <p>I tried to follow <a href="https://stackoverflow.com/questions/45967058/render-output-from-markdown-file-inside-rst-file">Render output from markdown file inside .rst file</a>, but this is not working. My <code>README.md</code> has some headings like</p>
  
  <pre><code># First heading
  
  some text
  
  ## Second heading 1
  
  some text
  
  ## Second heading 2
  
  some text
  </code></pre>
  
  <p>and I get the error <code>WARNING: ../README.md:48: (SEVERE/4) Title level inconsistent:</code>. I understand from <a href="https://stackoverflow.com/questions/24504301/what-does-title-level-inconsistent-mean">What does &quot;Title level inconsistent&quot; mean?</a> that I need to use other symbols - but reading into them I realized that the answer refers to <code>rst</code> symbols. That would mean that my markdown readme actually wasn't transformed into <code>rst</code>.</p>
  
  <p>PS: Someone else who tried something like that is
  <a href="https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/" rel="noreferrer">https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/</a></p>