Merge pull request #1738 from writethedocs/myst-port

writethedocs · May 25, 2022 · 58b9c1e · 58b9c1e
2 parents 28dbfe1 + 003eed6
commit 58b9c1e
Show file tree

Hide file tree

Showing 10 changed files with 50 additions and 60 deletions.
diff --git a/docs/blog/newsletter-december-2016.md b/docs/blog/newsletter-december-2016.md
@@ -1,8 +1,7 @@
-```eval_rst
-
-.. post:: Dec 5, 2016
-   :tags: newsletter
-
+```{post} Dec 5, 2016
+---
+tags: newsletter
+---
 ```
 
 # Write the Docs Newsletter - December 2016

diff --git a/docs/blog/newsletter-march-2017.md b/docs/blog/newsletter-march-2017.md
@@ -1,7 +1,7 @@
-```eval_rst
-
-.. post:: Mar 14, 2017
-   :tags: newsletter, march, formatting, bylines, alt text, job titles, community
+```{post} Mar 14, 2017
+---
+tags: newsletter, march, formatting, bylines, alt text, job titles, community
+---
 
 ```
 

diff --git a/docs/blog/newsletter-november-2016.md b/docs/blog/newsletter-november-2016.md
@@ -1,7 +1,7 @@
-```eval_rst
-
-.. post:: Nov 3, 2016
-   :tags: newsletter, november, 
+```{post} Nov 3, 2016
+---
+tags: newsletter, november,
+---
 
 ```
 
@@ -62,7 +62,6 @@ All of that said, a handful of solutions and platforms were mentioned in the con
 * [Forestry](https://forestry.io/) – builds a CMS from a repo of your Jekyll or Hugo project
 * [CraftCMS](https://craftcms.com) – user-friendly CMS, handy if you have non-techy folks contributing to your docs
 
-
 ## Using abbreviations and acronyms in documentation
 
 What started as a quick poll about how to abbreviate "input/output" – 'I/O' won handily over 'IO', 18:3 — quickly turned into a broader discussion about abbreviations in documentation on the whole. Here were some of the key questions and takeaways that emerged:

diff --git a/docs/blog/newsletter-october-2016.md b/docs/blog/newsletter-october-2016.md
@@ -1,7 +1,7 @@
-```eval_rst
-
-.. post:: Oct 3, 2016
-   :tags: newsletter
+```{post} Oct 3, 2016
+---
+tags: newsletter
+---
 
 ```
 
@@ -33,7 +33,6 @@ None of these are a perfect solution, perhaps, but they all give us somewhere to
 
 To help us with questions like the one above, Thursday Bram (@thursday) (one of our illustrious WtD speakers) and Audrey Eschright (founder and publisher of _[The Recompiler](https://recompilermag.com/)_) just successfully funded their Kickstarter campaign to publish the [Responsible Communication Guide](https://www.kickstarter.com/projects/961164339/the-responsible-communication-style-guide). The project will produce a cross-functional style guide to help people write about technology in way that is more sensitive and inclusive around questions of race, gender, sexuality, religion, and health. Definitely a project to keep an eye on—congratulations to everyone who worked so hard to get it funded!
 
-
 ## Writing and maintaining command reference pages
 
 On the technical side of things, early in the month a bunch of folks tackled the question of how best to put together command reference pages. For example, take a look at [http://redis.io/commands](http://redis.io/commands), [https://developer.wordpress.org/cli/commands/](https://developer.wordpress.org/cli/commands/), or [https://drushcommands.com/](https://drushcommands.com/).

diff --git a/docs/blog/newsletter-september-2016.md b/docs/blog/newsletter-september-2016.md
@@ -1,8 +1,7 @@
-```eval_rst
-
-.. post:: Sep 1, 2016
-   :tags: newsletter
-
+```{post} Sep 1, 2016
+---
+tags: newsletter
+---
 ```
 
 # Write the Docs Newsletter - September 2016
@@ -13,18 +12,12 @@ Hello Write the Docs! If you're getting this email, you've probably attended (or
 
 As part of that effort, we're sending you this, our inaugural edition of the new Write the Docs monthly newsletter! Our goal is to make it easier for folks to keep current with what the community's talking about each month. The bulk of the newsletter content will be distilled from interesting conversations that crop up on the #general channel of the [Write the Docs Slack ](http://slack.writethedocs.org/). We'll be highlighting topics that are recurring themes or simply seem to resonate with a lot of folks.
 
-```eval_rst
 
-.. note:: We know the #general channel is just one arena for docs talk. If  you see a conversation elsewhere on Slack (or Twitter or wherever) that would make good newsletter fodder, ping our editor, `Kelly O'Brien <https://www.writethedocs.org/team/#newsletter-team>`_.
+```{note}
+We know the #general channel is just one arena for docs talk. If  you see a conversation elsewhere on Slack (or Twitter or wherever) that would make good newsletter fodder, ping our editor, [Kelly O'Brien](https://www.writethedocs.org/team/#newsletter-team).
 
 ```
 
-```eval_rst
-
-.. only:: email
-
-    If this sounds like fun, awesome! Consider yourself subscribed! If you'd rather keep our emails limited to just conference-related notices, that's fine too. Just `click here to select which emails you get <*|UPDATE_PROFILE|*>`_ from the newsletter list.
-```
 
 And without further ado, here's a few topics of conversation from this past month that tickled our fancy:
 
@@ -43,13 +36,11 @@ There were also a handful of great suggestions for UI copy best practices:
 
 If you're looking for more info about UI help text, check out Beth Aitman's talk on the subject from Write the Docs EU 2015. For more on progressive disclosure, try this blog post: [Masking Complexity through Progressive Disclosure](https://blog.recurly.com/2013/04/masking-complexity-through-progressive-disclosure),
 
-
 ## Metrics case study: Total Time Reading (TTR)
 
 Who doesn't love talking about documentation metrics? (No one, that's who.) One of the Write the Docs co-founders, Troy Howard, has a new blog post out, in which he takes a close look at Total Time Reading (TTR) as a way of judging the success of a page or article. If documentation metrics is your thing, it's definitely worth a read:
 [TechDocs Metrics Case Study: Total Time Reading (TTR)](http://blog.thoward37.me/articles/techdocs-metrics-total-time-reading-(ttr))
 
-
 ## Code review versus copy review
 
 Another blog post that spurred conversation was this one from the Atlassian blog, [The (written) unwritten guide to pull requests](http://blogs.atlassian.com/2016/07/written-unwritten-guide-pull-requests/). In addition to having lots of good pointers for, y'know, doing code reviews, it also sparked a conversation about some of those same techniques can be used to conduct copy reviews on your docs.

diff --git a/docs/conf.py b/docs/conf.py
@@ -6,7 +6,6 @@
 
 import yaml
 import ablog
-from recommonmark.transform import AutoStructify
 
 # Only for windows compatibility - Forces default encoding to UTF8, which it may not be on windows
 if os.name == 'nt':
@@ -64,8 +63,11 @@
     'sphinxcontrib.datatemplates',
     'notfound.extension',
     'sphinxemoji.sphinxemoji',
-    'recommonmark',
+    'myst_parser',
 ]
+
+myst_heading_anchors = 4
+
 blog_baseurl = 'https://www.writethedocs.org/'
 blog_path = 'blog/archive'
 blog_authors = {
@@ -199,12 +201,6 @@ def setup(app):
 
     app.add_directive('meetup-listing', MeetupListing)
     app.add_directive('datatemplate-video', videos.DataTemplateVideo)
-    app.add_config_value('recommonmark_config', {
-        'auto_toc_tree_section': 'Contents',
-        # 'enable_auto_doc_ref': True,
-        'enable_eval_rst': True,
-    }, True)
-    app.add_transform(AutoStructify)
     app.add_css_file('css/global-customizations.css')
     app.add_css_file('css/survey.css')
     app.add_js_file('js/jobs.js')

diff --git a/docs/hiring-guide/freelancing/business-identity.md b/docs/hiring-guide/freelancing/business-identity.md
@@ -10,9 +10,8 @@ Your business identity is how you position yourself in the market, and your corp
 "I love the startup vibe."
 
 #### Related  
-[Core values > What sort of work do I want to do?](../core-values#what-sort-of-work-do-i-want-to-do)  
-[Core values > Where do I want to work?](../core-values#where-do-i-want-to-work)  
-
+[Core values > What sort of work do I want to do?](core-values.md#what-sort-of-work-do-i-want-to-do)
+[Core values > Where do I want to work?](core-values.md#where-do-i-want-to-work)
 
 ### How do I present myself to the world / what is the tone of my interaction with clients?
 
@@ -21,8 +20,8 @@ Your business identity is how you position yourself in the market, and your corp
 "I will adapt to each client's tone."
 
 #### Related
-[Core values > What sort of relationship do I want with my clients?](../core-values#what-sort-of-relationship-do-i-want-with-my-clients)  
-[Core values > How much of myself do I want in my work?](../core-values#how-much-of-myself-do-i-want-in-my-work)
+[Core values > What sort of relationship do I want with my clients?](core-values.md#what-sort-of-relationship-do-i-want-with-my-clients)
+[Core values > How much of myself do I want in my work?](core-values.md#how-much-of-myself-do-i-want-in-my-work)
 
 ### What do I offer my client?
 
@@ -34,7 +33,7 @@ Think about your value proposition. Be specialized: the clearer you are about yo
 
 #### Related
 
-[Core values > What sort of work do I want to do?](../core-values#what-sort-of-work-do-i-want-to-do)
+[Core values > What sort of work do I want to do?](core-values.md#what-sort-of-work-do-i-want-to-do)
 
 ### What tools do I specialize in?
 

diff --git a/docs/hiring-guide/freelancing/business-plan.md b/docs/hiring-guide/freelancing/business-plan.md
@@ -12,9 +12,9 @@ Your business plan is the practical implementation of the [values](core-values.m
 
 #### Related
 
-[Core values > What sort of work do I want to do?](../core-values#what-sort-of-work-do-i-want-to-do)  
-[Core values > Where do I want to work?](../core-values#where-do-i-want-to-work)  
-[Business identity > What type of clients do I want?](../business-identity#what-type-of-clients-do-i-want)  
+[Core values > What sort of work do I want to do?](core-values.md#what-sort-of-work-do-i-want-to-do)
+[Core values > Where do I want to work?](core-values.md#where-do-i-want-to-work)
+[Business identity > What type of clients do I want?](business-identity.md#what-type-of-clients-do-i-want)
 [Finding work](find-work.md)
 
 ### What are my rates?
@@ -39,7 +39,7 @@ A range of factors contribute to your rates:
 
 #### Related
 
-[Business identity > What type of clients do I want?](../business-identity#what-type-of-clients-do-i-want) 
+[Business identity > What type of clients do I want?](business-identity.md#what-type-of-clients-do-i-want)
 
 ### Where do I want to be in *X* years?
 
@@ -50,9 +50,8 @@ A range of factors contribute to your rates:
 
 #### Related
 
-[Core values > Why do I want to freelance?](../core-values#why-do-i-want-to-freelance)  
-[Core values > What is my key motivator?](../core-values#what-is-my-key-motivator)
-
+[Core values > Why do I want to freelance?](core-values.md#why-do-i-want-to-freelance)
+[Core values > What is my key motivator?](core-values.md#what-is-my-key-motivator)
 
 ## Template
 

diff --git a/docs/news/call_for_organizers.md b/docs/news/call_for_organizers.md
@@ -8,7 +8,7 @@ but it takes some additional planning and it will help if you have some familiar
 Said familiarity is not required, but if you don't know DC, it could affect the organizer roles that
 make sense for you to assume.
 
-### Location and Venue
+# Location and Venue
 
 Jennifer Rondeau, co-organizer of WTD NA in Portland for two years now, recently moved to DC,
 and is willing to be organizer in chief on the ground, so the DC area might make the most sense.

diff --git a/requirements.txt b/requirements.txt
@@ -1,10 +1,19 @@
 Sphinx==4.5.0
-recommonmark==0.7.1
-ablog==0.10.6  # pyup: ignore
+
+# make livehtml support
 sphinx_autobuild==2021.3.14
-PyYAML>=4.2b1
+
+# Markdown support
+myst-parser==0.17.2
+
+# Blogging
+ablog==0.10.6  # pyup: ignore
+
 # Sphinx (checked with 4.3) requires docutils=<0.18
 docutils==0.17.1   # pyup: <0.18
+PyYAML>=4.2b1
+
+# Additional libraries
 csvkit==1.0.7
 yamllint==1.26.3
 pathlib==1.0.1
@@ -21,4 +30,3 @@ sphinxemoji==0.2.0
 Werkzeug==0.16.1 # pyup: <1.0
 # For fancy 404 pages
 sphinx-notfound-page==0.8
-