From ef726d79a46aaa74c6205a5abdf4a94f69c57c7f Mon Sep 17 00:00:00 2001
From: Antonio <zolotuhin87@gmail.com>
Date: Sat, 9 Apr 2022 18:28:28 +0300
Subject: [PATCH] docs: added tutorial on how to use lang and output extensions
 together

---
 docs/tutorials/index.md                       |  3 +-
 .../use-both-extension-types-together.md      | 62 +++++++++++++++++++
 2 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 docs/tutorials/use-both-extension-types-together.md

diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
index ade28a9..86720a8 100644
--- a/docs/tutorials/index.md
+++ b/docs/tutorials/index.md
@@ -1,4 +1,5 @@
 # Tutorials
 
 * [Add default class for each HTML element](add-default-class-to-html.md)
-* [Markdown editor with Showdown](markdown-editor-with-showdown.md)
\ No newline at end of file
+* [Markdown editor with Showdown](markdown-editor-with-showdown.md)
+* [Use language and output extensions on the same block](use-both-extension-types-together.md)
\ No newline at end of file
diff --git a/docs/tutorials/use-both-extension-types-together.md b/docs/tutorials/use-both-extension-types-together.md
new file mode 100644
index 0000000..6b673b7
--- /dev/null
+++ b/docs/tutorials/use-both-extension-types-together.md
@@ -0,0 +1,62 @@
+# Use language and output extensions on the same block
+
+## Overview
+
+Showdown allows you to define and use any number of extensions that act on the same block. These extensions can be executed sequentially or at different moments.
+
+This enables you to pre-parse/mark a block of text but defer any modifications for the last by using a combination of language and output extensions.
+
+This is useful if you, for example, don't want Showdown to parse the contents of your new language construct.
+
+## Example
+
+Let's say you create an extension that captures everything between `%start%` and `%end%`. However, that content should not be modified by Showdown. Obviously, you can use `<pre>` tags but that is beside the point.
+
+Although Showdown doesn't have any flag to prevent parsing the content of an extension, the same effect can be easily achieved by using lang and output extensions together.
+
+!!! example ""
+    The fully working example you can see in [Fiddle][1].
+
+### Code
+
+[Create your extensions](../create-extension.md) with the following content:
+
+```js
+showdown.extension('myExt', function() {
+  var matches = [];
+  return [
+    { 
+      type: 'lang',
+      regex: /%start%([^]+?)%end%/gi,
+      replace: function(s, match) { 
+        matches.push(match);
+        var n = matches.length - 1;
+        return '%PLACEHOLDER' + n + '%';
+      }
+    },
+    {
+      type: 'output',
+      filter: function (text) {
+        for (var i=0; i< matches.length; ++i) {
+          var pat = '<p>%PLACEHOLDER' + i + '% *<\/p>';
+          text = text.replace(new RegExp(pat, 'gi'), matches[i]);
+        }
+        //reset array
+        matches = [];
+        return text;
+      }
+    }
+  ]
+});
+```
+
+In this example, you created a [`lang` extension](../create-extension.md#type) that:
+
+1. Checks for the pseudo tags `%start%` and `%end%`.
+1. Extracts everything in between the tags.
+1. Saves the content between the tags in a variable.
+1. Replaces the saved content with a placeholder to identify the exact position of the extracted text.
+
+and an [`output` extension](../create-extension.md#type) that replaces the placeholder with the saved content, once Showdown is finished parsing.
+
+[1]: http://jsfiddle.net/tivie/1rqr7xy8/
\ No newline at end of file