chore: update docs

docs/_templates/partials/sidebar-links.html

@@ -0,0 +1,5 @@
+<div class="sponsor" style="background:rgba(0,0,0,.05);padding:15px;margin:1rem 0;border-radius:6px;text-align:center">
+  <a style="display: flex;justify-content: center;margin-bottom: 0.5rem;" href="https://typlog.com/"><img src="https://typlog.com/android-chrome-512x512.png" alt="Typlog" width="100" height="100"></a>
+  <div class="text" style="font-size:0.86rem"><a href="https://typlog.com/?utm_source=mistune&utm_medium=docs">A blogging and podcast hosting platform, simple yet elegant.</a></div>
+</div>
+<div class="js-carbon" data-carbon-code="CE7DKK3W" data-carbon-placement="mistune"></div>

docs/api.rst

@@ -105,6 +105,21 @@ Plugins
 
 .. autofunction:: spoiler
 
+Renderers
+---------
+
+.. module:: mistune.renderers.html
+
+.. autoclass:: HTMLRenderer
+
+.. module:: mistune.renderers.markdown
+
+.. autoclass:: MarkdownRenderer
+
+.. module:: mistune.renderers.rst
+
+.. autoclass:: RSTRenderer
+
 TOC hook
 --------
 

docs/conf.py

@@ -41,6 +41,21 @@
     'twitter_url': 'https://twitter.com/lepture',
     'github_url': 'https://github.com/lepture/mistune',
     'nav_links': [
+        {
+            'title': 'Projects',
+            'children': [
+                {
+                    'title': 'Authlib',
+                    'url': 'https://authlib.org/',
+                    'summary': 'OAuth, JOSE, OpenID, etc'
+                },
+                {
+                    'title': 'Shibuya',
+                    'url': 'https://shibuya.lepture.com/',
+                    'summary': 'A pretty Sphinx theme',
+                }
+            ]
+        },
         {'title': 'Sponsor me', 'url': 'https://github.com/sponsors/lepture'}
     ]
 }
@@ -54,12 +69,3 @@
 html_show_sourcelink = False
 
 html_favicon = "_static/light-icon.svg"
-html_sidebars = {
-    "**": [
-        "sidebars/localtoc.html",
-        "sidebars/repo-stats.html",
-        "sidebars/edit-this-page.html",
-        "sponsors.html",
-        "sidebars/ethical-ads.html",
-    ]
-}

docs/guide.rst

@@ -83,8 +83,8 @@ In this way, we can use Pygments to highlight the fenced code. Learn more
 at :ref:`renderers`.
 
 
-AST
----
+Abstract syntax tree
+--------------------
 
 Mistune can produce AST by default without any renderer::
 

docs/plugins.rst

@@ -6,6 +6,10 @@ Built-in Plugins
 .. meta::
     :description: List of Mistune built-in plugins, their syntax and how to enable them.
 
+Mistune offers many built-in plugins, including all the popular markups.
+
+.. _strikethrough:
+
 strikethrough
 -------------
 

docs/renderers.rst

@@ -3,15 +3,31 @@
 Renderers
 =========
 
+Mistune has several built-in renderers, including:
+
+- :class:`mistune.renderers.html.HTMLRenderer`
+- :class:`mistune.renderers.markdown.MarkdownRenderer`
+- :class:`mistune.renderers.rst.RSTRenderer`
+
+You're welcome to contribute more renderers.
 
 Customize HTMLRenderer
 ----------------------
 
-You can customize HTML output with your own renderers. Create a subclass
-of ``mistune.HTMLRenderer``::
+You can customize HTML output with your own renderers. Take an example, we're going
+to add an inline math syntax like below:
+
+.. code::
+
+    `$a^2=4$`
+
+To render this syntax, we can create a subclass of ``mistune.HTMLRenderer``:
+
+.. code-block:: python
 
+    from mistune import HTMLRenderer
 
-    class MyRenderer(mistune.HTMLRenderer):
+    class MyRenderer(HTMLRenderer):
         def codespan(self, text):
             if text.startswith('$') and text.endswith('$'):
                 return '<span class="math">' + escape(text) + '</span>'
@@ -21,7 +37,12 @@ of ``mistune.HTMLRenderer``::
     markdown = mistune.create_markdown(renderer=MyRenderer())
     print(markdown('hi `$a^2=4$`'))
 
-Here is a a list of available renderer functions::
+Available methods
+~~~~~~~~~~~~~~~~~
+
+Here is a a list of available renderer functions for ``HTMLRenderer``, including methods on plugins:
+
+.. code-block::
 
     # inline level
     text(self, text)
@@ -93,23 +114,53 @@ Here is a a list of available renderer functions::
 RestructuredText Renderer
 -------------------------
 
+The ``RSTRenderer`` can be used to convert markdown text to RestructuredText.
 
-Customize MarkdownRenderer
----------------------------
+.. code-block:: python
 
-You can customize Markdown output with your own renderers. Create a subclass
-of ``mistune.MarkdownRenderer``::
+    from mistune.renderers.rst import RSTRenderer
 
+    convert_rst = mistune.create_markdown(renderer=RSTRenderer())
+    convert_rst(your_markdown_text)
 
-    class MyRenderer(mistune.renderers.markdown.MarkdownRenderer):
-        def link(self, token, state):
-            return '**' + self.render_children(token, state) + '** '
 
-    # use customized renderer
-    markdown = mistune.create_markdown(renderer=MyRenderer())
-    print(markdown('[Mistune](mistune.lepture.com)'))
+Markdown Renderer
+-----------------
+
+The ``MarkdownRenderer`` can be used to reformat your Markdown text.
+
+.. code-block:: python
+
+    from mistune.renderers.markdown import MarkdownRenderer
+
+    format_markdown = mistune.create_markdown(renderer=MarkdownRenderer())
+    format_markdown(your_markdown_text)
+
+With plugins
+~~~~~~~~~~~~
+
+The original ``MarkdownRenderer`` can **ONLY** render the basic Markdown syntax.
+If you're using plugins, you would need to customize ``MarkdownRenderer`` with
+extra render methods. Take an example, you are going to add the :ref:`strikethrough`
+plugin:
+
+.. code-block:: python
+
+    from mistune.renderers.markdown import MarkdownRenderer
+
+    class MyRenderer(MarkdownRenderer):
+        def strikethrough(self, token, state):
+            return '~~' + self.render_children(token, state) + '~~'
+
+    format_markdown = mistune.create_markdown(renderer=MarkdownRenderer(), plugins=['strikethrough'])
+    format_markdown(your_markdown_text)
+
+Default methods
+~~~~~~~~~~~~~~~
+
+Here is a a list of default renderer functions of ``MarkdownRenderer``:
 
-Here is a a list of available renderer functions::
+.. code-block::
 
     # inline level
     text(self, token, state)

serve-doc.py

@@ -1,5 +1,5 @@
 from livereload import Server, shell
 
 app = Server()
-app.watch("docs", shell("make docs"), delay=2)
+app.watch("docs/*.rst", shell("make docs"), delay=2)
 app.serve(root="docs/_build/html/")