-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
bc218f8
commit 26ddbb4
Showing
22 changed files
with
726 additions
and
47 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,125 @@ | ||
| <!DOCTYPE html> | ||
| <!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]--> | ||
| <!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]--> | ||
| <!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]--> | ||
| <!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]--> | ||
| <head> | ||
| <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> | ||
| <meta name="description" property="og:description" content="Migrating from RST to Markdown Everywhere I used to use RST (ReStructured Text) format for all my FOSS documentation, internal note taking and even for Python docstrings. However, I’ve decided to make my life simpler by using Markdown everywhere. This change came about around the summer of 2023. Since …"> | ||
|
|
||
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.3.1/css/bootstrap.min.css"> | ||
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.3.1/css/bootstrap-responsive.min.css"> | ||
| <link rel="stylesheet" href="https://jamescooke.info/theme/droidstrap.css"> | ||
| <link href='https://fonts.googleapis.com/css?family=Droid+Sans:400,700|Droid+Sans+Mono|Droid+Serif:400,700,400italic,700italic' rel='stylesheet' type='text/css'> | ||
|
|
||
|
|
||
| <script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script> | ||
|
|
||
|
|
||
| <title>TODO ReST to MD // James Cooke // Brighton-based Python developer</title> | ||
| <meta charset="utf-8" /> | ||
| <meta name="viewport" content="width=device-width"> | ||
| </head> | ||
|
|
||
| <body> | ||
| <!--[if lt IE 7]> | ||
| <p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="https://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p> | ||
| <![endif]--> | ||
| <div class="fake"> </div> | ||
| <div class="container"> | ||
| <div class="row"> | ||
| <header class="span3"> | ||
| <h1 class="blogtitle"> | ||
| <a href="https://jamescooke.info"><img id="profileimg" src="/images/coding_cooke_ltd.png" alt="James Cooke" ></a>James Cooke | ||
| </h1> | ||
| <nav> | ||
| <ul> | ||
| <li><a href="/">Home</a></li> | ||
| <li><a href="/pages/hello-my-name-is-james.html">About</a></li> | ||
| <li><a href="/feeds/all.atom.xml">Atom Feed</a></li> | ||
| </ul> | ||
| </nav> | ||
| </header> | ||
|
|
||
| <section class="span7 offset1 content"> | ||
| <article class="blogpost"> | ||
| <header> | ||
| <h1><span class="caps">TODO</span> ReST to <span class="caps">MD</span></h1> | ||
| <p class="postdate" title="9999-12-31T23:59:59.999999-00:01">- Posted </p> | ||
| </header> | ||
| <div class='article-content'> | ||
| <h1>Migrating from <span class="caps">RST</span> to Markdown</h1> | ||
| <p><em>Everywhere</em></p> | ||
| <p>I used to use <span class="caps">RST</span> (ReStructured Text) format for all my <span class="caps">FOSS</span> documentation, internal note taking and even for Python docstrings.</p> | ||
| <p>However, I’ve decided to make my life simpler by using Markdown everywhere.</p> | ||
| <p>This change came about around the summer of 2023. Since then all posts on this blog have been in Markdown (yes all <span class="caps">FOUR</span> of them).</p> | ||
| <p>Essentially the change happened because I’ve improved my workflow for Markdown documents because they are the standard at work. In fact, thinking back, I can’t think of a work project that I’ve <em>ever</em> contributed to that <em>didn’t</em> use Markdown for documentation stored in repositories.</p> | ||
| <p>As we’ve worked to improve and upgrade the quality of our work documentation, I’ve also improved my local workflow. I use Frogmouth to render Markdown documents alongside my editor in Vim. We’ve used https://github.com/DavidAnson/markdownlint/ at work to nail down consistency, but I’ve not wired it into my workflow at home or work yet.</p> | ||
| <p>However, all this effort, and the fact I’ve finally learned how to do links in Markdown <code>[ ]( )</code>, means that I’m in a much better place to switch over to it.</p> | ||
| <p>Making the switch.</p> | ||
| <p>I’ve been using <code>pandoc</code> to make <span class="caps">RST</span> to <span class="caps">MD</span> conversions. It’s not perfect and I have to fix things up by hand afterwards, but it gets the bulk of the document “right”.</p> | ||
| <div class="highlight"><pre><span></span><code>pandoc -s -o rc.md release_checklist.rst | ||
| </code></pre></div> | ||
|
|
||
| <p>The annoying thing has been keeping history for those docs in git. For this I run the following:</p> | ||
| <ul> | ||
| <li>Make an initial Markdown clone of the document.</li> | ||
| <li><code>git mv</code> the existing <span class="caps">RST</span> document to its new <span class="caps">MD</span> filename.</li> | ||
| <li>Move the Markdown clone over the top of the markdown document.</li> | ||
| </ul> | ||
| <p>Most recently, I’ve converted the Flake8-<span class="caps">AAA</span> release checklist document from <span class="caps">RST</span> to Markdown. So, working in the <code>/docs</code> directory of that project:</p> | ||
| <div class="highlight"><pre><span></span><code>pandoc<span class="w"> </span>-s<span class="w"> </span>-o<span class="w"> </span>/tmp/rc.md<span class="w"> </span>release_checklist.rst | ||
| </code></pre></div> | ||
|
|
||
| <ol> | ||
| <li>move</li> | ||
| </ol> | ||
| <div class="highlight"><pre><span></span><code>git<span class="w"> </span>mv<span class="w"> </span>release_checklist.rst<span class="w"> </span>release_checklist.md | ||
| </code></pre></div> | ||
|
|
||
| <ol> | ||
| <li>Dump the converted file</li> | ||
| </ol> | ||
| <div class="highlight"><pre><span></span><code>mv<span class="w"> </span>/tmp/rc.md<span class="w"> </span>release_checklist.md | ||
| </code></pre></div> | ||
|
|
||
| <p>Now at this stage, I usually hand-edit the changes and commit the move and edit at the same time, but you might be more cautious and want to commit the move, and then the edits on top.</p> | ||
| <h2>Issues</h2> | ||
| <p>At a personal level, I’ve not had any issues using Markdown over <span class="caps">RST</span>.</p> | ||
| <p>I find it easier to write and easier to render in terminal.</p> | ||
| <p>This blog is running the Pelican static site generator and that handles the Markdown just fine.</p> | ||
| <p>So I’ll continue using Markdown everywhere.</p> | ||
| <p>There might be interesting issues at an organisational level - this <a href="https://hachyderm.io/@remoquete/112168229391465692">Toot was | ||
| really interesting</a> and | ||
| mentions pros and cons of using Markdown for technical documentation (I think | ||
| “within a team” is implied).</p> | ||
| </div> | ||
| </article> | ||
|
|
||
| <hr /> | ||
|
|
||
| <p class="article-meta"> | ||
| – | ||
| Posted in <a href="https://jamescooke.info/category/zzz-misc.html">ZZZ Misc...</a> | ||
|
|
||
| </p> | ||
|
|
||
| <hr /> | ||
|
|
||
|
|
||
|
|
||
| </section> | ||
|
|
||
| </div> | ||
| <div class="row"> | ||
| <footer class="offset4 span7"> | ||
| <p>© James Cooke – | ||
| Built with <a href="https://github.com/jamescooke/droidstrap">Droidstrap theme</a> | ||
| for <a href="https://blog.getpelican.com/">Pelican</a> | ||
| </p> | ||
| <p>Licensed under <a rel="license" href="https://creativecommons.org/licenses/by-sa/3.0/deed.en_GB">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.</p> | ||
| </footer> | ||
| </div> | ||
|
|
||
| </body> | ||
| </html> |
Oops, something went wrong.