diff --git a/web_widget_html_markdown/README.rst b/web_widget_html_markdown/README.rst
new file mode 100644
index 000000000000..ee5397ff3176
--- /dev/null
+++ b/web_widget_html_markdown/README.rst
@@ -0,0 +1,114 @@
+========================
+Web Widget Html Markdown
+========================
+
+.. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Beta
+.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
+    :alt: License: AGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fweb-lightgray.png?logo=github
+    :target: https://github.com/OCA/web/tree/14/web_widget_html_markdown
+    :alt: OCA/web
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/web-14/web-14-web_widget_html_markdown
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runbot-Try%20me-875A7B.png
+    :target: https://runbot.odoo-community.org/runbot/162/14
+    :alt: Try me on Runbot
+
+|badge1| |badge2| |badge3| |badge4| |badge5| 
+
+Behaviour of the module and best practices
+==========================================
+
+This module implements a Markdown editor on Html fields, in contrast to web_widget_text_markdown, which implements it on Text fields. In readonly mode, the widget displays HTML, but when editing, the widget offers you an option to edit in Markdown or in HTML. If you edit markdown, it will save as the rendered HTML, but with the source Markdown embedded inside a <script> tag. When editing again, it will show you the Markdown source. If you edit HTML, you will lose the Markdown and the content will just behave as a regular HTML field with an HTML widget.
+
+Utility of this module vs web_widget_text_markdown
+==================================================
+The benefit of this module over web_widget_text_html is that it allows markdown-editing of HTML fields such as for example the mail.message body for the chatter, or HTML fields that end up in printed reports such as the Quotation description. Such fields cannot be converted to Text fields because it will cause problems for their functionality. But with this widget, they can still be edited as Markdown.
+
+A difficulty with this module is that once you start editing a field as HTML, whether with this Markdown widget in HTML mode, or through a view that has the normal HTML editor, you will lose the Markdown source and you will have to keep editing the field as HTML, or do a backconversion to Markdown. This backconversion is always lossy to a certain extent and we did not bother implementing it - but it's something for the roadmap.
+.
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Usage
+=====
+
+Your XML form view definition should contain:
+
+    ...
+    <field name="field_name" widget="html_markdown"/>
+    ...
+
+This will replace the default Html widget with the new Markdown/HTML widget and
+allow the field to be edited as Markdown or HTML, depending on the user's choice.
+
+  #### Options
+      - default_markdown_on_new : if true when creating a new record, markdown will 
+        be selected by default.
+      - only_markdown_on_new : if true when creating a new record, only markdown
+        will be present on radiobutton.
+
+Known issues / Roadmap
+======================
+
+* Implement conversion from HTML to Markdown, either through a JS or a Python module, instead of not allowing it, or allowing it only after HTML is emptied.
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/web/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us smashing it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/web/issues/new?body=module:%20web_widget_html_markdown%0Aversion:%2014%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+~~~~~~~
+
+* Giovanni Francesco Capalbo
+* Therp B.V.
+
+Contributors
+~~~~~~~~~~~~
+
+* Tom Blauwendraat <tom@sunflowerweb.nl>
+* Kevin Kamau <kevin@sunflowerweb.nl>
+* Giovanni Francesco Capalbo <giovanni@therp.nl>
+
+Other credits
+~~~~~~~~~~~~~
+
+* Therp B.V. <https://therp.nl>
+
+Maintainers
+~~~~~~~~~~~
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+This module is part of the `OCA/web <https://github.com/OCA/web/tree/14/web_widget_html_markdown>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
diff --git a/web_widget_html_markdown/static/description/index.html b/web_widget_html_markdown/static/description/index.html
index 264b0b0c09f7..b1be46ad3011 100644
--- a/web_widget_html_markdown/static/description/index.html
+++ b/web_widget_html_markdown/static/description/index.html
@@ -4,7 +4,7 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils: http://docutils.sourceforge.net/" />
-<title>Web Widget Html Markdown Unidirectional</title>
+<title>Web Widget Html Markdown</title>
 <style type="text/css">
 
 /*
@@ -360,8 +360,8 @@
 </style>
 </head>
 <body>
-<div class="document" id="web-widget-html-markdown-unidirectional">
-<h1 class="title">Web Widget Html Markdown Unidirectional</h1>
+<div class="document" id="web-widget-html-markdown">
+<h1 class="title">Web Widget Html Markdown</h1>
 
 <!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! This file is generated by oca-gen-addon-readme !!
@@ -370,36 +370,13 @@ <h1 class="title">Web Widget Html Markdown Unidirectional</h1>
 <p><a class="reference external" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external" href="https://github.com/OCA/web/tree/14/web_widget_html_markdown"><img alt="OCA/web" src="https://img.shields.io/badge/github-OCA%2Fweb-lightgray.png?logo=github" /></a> <a class="reference external" href="https://translation.odoo-community.org/projects/web-14/web-14-web_widget_html_markdown"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external" href="https://runbot.odoo-community.org/runbot/162/14"><img alt="Try me on Runbot" src="https://img.shields.io/badge/runbot-Try%20me-875A7B.png" /></a></p>
 <div class="section" id="behaviour-of-the-module-and-best-practices">
 <h1>Behaviour of the module and best practices</h1>
-<ul class="simple">
-<li>In readonly mode, the widget renders as Html</li>
-<li>In editable mode, there is a switcher to choose if the source should be HTML or Markdown. If HTML, it shows the HTML edit widget. If Markdown, it shows a markdown widget. When done editing, it will save in the field as Html, no matter which widget is chosen.</li>
-<li><dl class="first docutils">
-<dt>The Module converts only from markdown to html, so if i am writing HTML and then switch to markdown, i will lose all my HTML.</dt>
-<dd><ul class="first last">
-<li>when switching from markdown to HTML: the markdown will always be converted and saved in html.</li>
-<li>if I switch again from HTML to markdown, i will lose all my html again, only the part i wrote in markdown will be preserved.</li>
-</ul>
-</dd>
-</dl>
-</li>
-<li>Module provides a warning “You will lose all your current HTML if you switch to markdown”</li>
-<li><dl class="first docutils">
-<dt>Best usages of this module:</dt>
-<dd><ol class="first last arabic">
-<li>As normal Html editor, only HTML</li>
-<li>Write some markdown and then add some HTML. ( will cause loss of HTML if you edit markdown again)</li>
-<li>Only markdown.</li>
-</ol>
-</dd>
-</dl>
-</li>
-<li>RE-editing pure markdown content is LOSSLESS because we preserve the markdown content in a special tag.</li>
-<li>Every switch to markdown will cause destruction of HTML. Html Can Be added after writing Markdown part but will always be deleted.</li>
-</ul>
+<p>This module implements a Markdown editor on Html fields, in contrast to web_widget_text_markdown, which implements it on Text fields. In readonly mode, the widget displays HTML, but when editing, the widget offers you an option to edit in Markdown or in HTML. If you edit markdown, it will save as the rendered HTML, but with the source Markdown embedded inside a &lt;script&gt; tag. When editing again, it will show you the Markdown source. If you edit HTML, you will lose the Markdown and the content will just behave as a regular HTML field with an HTML widget.</p>
 </div>
 <div class="section" id="utility-of-this-module-vs-web-widget-text-markdown">
 <h1>Utility of this module vs web_widget_text_markdown</h1>
-<p>Why this module when web_widget_text_markdown already exists? Mainly because it is designed to work on Text fields, and most fields within Odoo are HTML fields for example: mail content, project.task description etc. Although you could develop a custom module that overrides these fields to be Text fields and render them on-screen as HTML, this rendering would not be done when the field is for example used in sending out a mail or fetching the field content through Odoo API. In these cases this widget comes in handy because it is plug-and-play: the field type and content remains as HTML, but you can choose to edit it with a markdown widget.</p>
+<p>The benefit of this module over web_widget_text_html is that it allows markdown-editing of HTML fields such as for example the mail.message body for the chatter, or HTML fields that end up in printed reports such as the Quotation description. Such fields cannot be converted to Text fields because it will cause problems for their functionality. But with this widget, they can still be edited as Markdown.</p>
+<p>A difficulty with this module is that once you start editing a field as HTML, whether with this Markdown widget in HTML mode, or through a view that has the normal HTML editor, you will lose the Markdown source and you will have to keep editing the field as HTML, or do a backconversion to Markdown. This backconversion is always lossy to a certain extent and we did not bother implementing it - but it’s something for the roadmap.
+.</p>
 <p><strong>Table of contents</strong></p>
 </div>
 <div class="section" id="usage">
@@ -409,9 +386,7 @@ <h1>Usage</h1>
 …
 &lt;field name=”field_name” widget=”html_markdown”/&gt;
 …</blockquote>
-<p>The widget is used on a Html field to edit HTML or Markdown,
-but the conversion is unidirectional, ONLY from Markdown to HTML.</p>
-<p>This will replace the default Html widget by the new Markdown/HTML widget and
+<p>This will replace the default Html widget with the new Markdown/HTML widget and
 allow the field to be edited as Markdown or HTML, depending on the user’s choice.</p>
 <blockquote>
 <dl class="docutils">
@@ -429,7 +404,7 @@ <h1>Usage</h1>
 <div class="section" id="known-issues-roadmap">
 <h1>Known issues / Roadmap</h1>
 <ul class="simple">
-<li>HTML Will be lost when passing from Html to markdown</li>
+<li>Implement conversion from HTML to Markdown, either through a JS or a Python module, instead of not allowing it, or allowing it only after HTML is emptied.</li>
 </ul>
 </div>
 <div class="section" id="bug-tracker">
@@ -446,9 +421,7 @@ <h1>Credits</h1>
 <h2>Authors</h2>
 <ul class="simple">
 <li>Giovanni Francesco Capalbo</li>
-<li>Therp B.V.Komit</li>
-<li>Sudokeys</li>
-<li>Sunflower IT</li>
+<li>Therp B.V.</li>
 </ul>
 </div>
 <div class="section" id="contributors">
@@ -462,7 +435,7 @@ <h2>Contributors</h2>
 <div class="section" id="other-credits">
 <h2>Other credits</h2>
 <ul class="simple">
-<li>Therp B.V. <a class="reference external" href="https://therp.nl">https://therp.nl</a></li>
+<li>Therp B.V. &lt;<a class="reference external" href="https://therp.nl">https://therp.nl</a>&gt;</li>
 </ul>
 </div>
 <div class="section" id="maintainers">
diff --git a/web_widget_html_markdown/static/src/js/web_widget_html_markdown.js b/web_widget_html_markdown/static/src/js/web_widget_html_markdown.js
index 97f427f081c5..a66b0daa4cc6 100644
--- a/web_widget_html_markdown/static/src/js/web_widget_html_markdown.js
+++ b/web_widget_html_markdown/static/src/js/web_widget_html_markdown.js
@@ -3,7 +3,6 @@
  * License AGPL-3.0 or later (https://www.gnu.org/licenses/agpl). */
 odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
     "use strict";
-
     var field_html = require('web_editor.field.html');
     var config = require('web.config');
     var core = require('web.core');
@@ -14,8 +13,7 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
     var _t = core._t;
     var _lt = core._lt;
     var LIBS_PATH = "/web_widget_html_markdown/static/src/lib/";
-    var CUST_LIBS_PATH = "/web_widget_html_markdown/static/src/css/";
-
+    var CUST_CSS_PATH = "/web_widget_html_markdown/static/src/css/";
 
     var FieldHtmlMarkDown = field_html.extend({
         description: _lt("HtmlMarkdown"),
@@ -28,10 +26,9 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
         ],
         cssLibs: [
             LIBS_PATH + "bootstrap-markdown.min.css",
-            CUST_LIBS_PATH + "web_widget_html_markdown.css",
+            CUST_CSS_PATH + "web_widget_html_markdown.css",
         ],
         xmlDependencies: ['/web_widget_html_markdown/static/src/xml/radio_info.xml'],
-
         /*=========================INIT AND START===============*/
         init: function (parent, options) {
             this._super.apply(this, arguments);
@@ -55,7 +52,6 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
             this.markdown_label = this.$el.find('label#markdown_label');
             this.html_label = this.$el.find('label#html_label');
         },
-
         /*=========================HTML WIDGET OVERIDES AND EXTENSIONS===============*/
         commitChanges: function () {
             var self = this;
@@ -82,7 +78,7 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                         self._isDirty = true;
                         _super();
                     });
-                 });
+                });
             }
         },
         reset: function (record, event) {
@@ -114,20 +110,16 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
             }
             return value;
         },
-
         _createWysiwygIntance: function () {
             /* 
              * in core this is named _createWysiwygIntance  (without the s), clearly a
-             * typo. It is used in renderEdit. When i had duplicated _renderEdit to use
-             * this function *instance it all worked. But as soon as i removed _renderEdit 
-             * and used the parent _renderEdit it would call _createWysiwygIntance
-             * and this , being called _createWysiwygInstance would never be called.
+             * typo. It is used in _renderEdit.
              * replicating the incorrect naming here too so all works.
              */
             var self = this;
             this.wysiwyg = new Wysiwyg(this, this._getWysiwygOptions());
             this.wysiwyg.__extraAssetsForIframe = this.__extraAssetsForIframe || [];
-            // By default this is synchronous because the assets are already loaded in willStart
+            // By default this is synchronous, the assets are  loaded in willStart
             // but it can be async in the case of options such as iframe, snippets...
             return this.wysiwyg.attachTo(this.$target).then(function () {
                 self.$content = self.wysiwyg.$editor.closest('body, odoo-wysiwyg-container');
@@ -136,7 +128,7 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                 if (self._html_has_md_source_tag() ) {
                     $(self.infoarea).html('<i>Markdown Fully Preserved, you can return to markdown with no loss</i>')
                     $(self.infoarea).attr('class' ,'md_preserved');
-                    // If there is a MD source tag and this WYSIWYG editor is not result of
+                    // If there is a MD source tag and is
                     // a switch but of a first load, start in markdown mode.
                     if (self.isSwitch == false) {
                         self.sw_html_to_mk()
@@ -153,14 +145,14 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                         self.input_markdown.hide();
                         self.markdown_label.hide();
                     } else {
-                       $(self.infoarea).addClass('md_preserved');
-                       $(self.infoarea).html('<i>Edit started in Html, If you start editing in HTML no markdown switching will be possible, if you need markdown, start editing markdown first. </i>')
+                        $(self.infoarea).addClass('md_preserved');
+                        $(self.infoarea).html('<i>Edit started in Html, If you start editing in HTML no markdown switching will be possible, if you need markdown, start editing markdown first. </i>')
                     }
-               }
+                }
             });
         },
         _onChange: function (ev) {
-            // a change has happened in HTML , destroy tag.
+            // a change has happened in HTML, destroy tag.
             this._rm_md_tag();
             if (this.switchable_to_markdown(ev)) {
                 this.input_markdown.show();
@@ -175,13 +167,12 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                 $(this.infoarea).html('<i>Html Edited, you cannot return to markdown. There is no Html->markdown conversion available in this version, next time start editing in markdown.</i>')
             }
             this._super.apply(this, arguments);
-       },
-       _renderReadonly: function () {
-           var self = this;
-           this._super.apply(this, arguments)
-           // parent returns nothing.
-       },
-
+        },
+        _renderReadonly: function () {
+            var self = this;
+            this._super.apply(this, arguments)
+            // parent returns nothing.
+        },
         /*=========================MARKDOWN EDITOR ===============*/
         _getMarkdownOptions: function () {
             var markdownOpts = {
@@ -196,7 +187,6 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                     return render_val;
                 },
             };
-
             // Only can create attachments on non-virtual records
             if (this.res_id) {
                 var self = this;
@@ -222,7 +212,6 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                         self._markdownDropZoneInit(this);
                     },
                 };
-
                 if (_t.database.multi_lang && this.field.translate) {
                     markdownOpts.additionalButtons = [
                         [{
@@ -237,11 +226,8 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                     ];
                 }
             }
-
             return markdownOpts;
-
         },
-
         _createMarkdownEditorInstance: function () {
             if (!this.markdownEditor) {
                 var markdownEditor ="<textarea  id='comment-md' rows='12' cols='100'></textarea>"
@@ -251,16 +237,14 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
                 );
             }
         },
-
         /*=========================TAG MANAGEMENT===========================*/
-
         _html_has_md_source_tag: function (){
             var tag = this.$content.find('.web_widget_html_markdown_source');
             return Boolean(tag.length)
         },
         _generate_md_tag: function(md_content) {
             var tag ="<p style=\"display:none;\" class=\"web_widget_html_markdown_source\" type=\"text/plain\">"+md_content + "</p>"
-             return tag
+            return tag
         },
         _rm_md_tag: function() {
             return this.$content.find('.web_widget_html_markdown_source').remove();
@@ -268,39 +252,32 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
         _get_md_tag_innertext: function() {
             var tag = this.$content.find('.web_widget_html_markdown_source')[0];
             if (tag){
-              return tag.innerText
+                return tag.innerText
             }
             return ""
         },
         _get_md_tag: function() {
             var tag = this.$content.find('.web_widget_html_markdown_source')[0];
-            if (tag){
+            if (tag) {
               return tag
             }
             return false
-
         },
         _html_is_empty: function() {
             //This will return us the latest content even if the widget is dirty.
             var current_value = this.wysiwyg.getValue()
             //Latest save value would had been: this._getValue()
-            //.isDirty will give us:
-            // this.wysiwyg.getValue() != this._getValue()
+            //.isDirty will give us:  this.wysiwyg.getValue() != this._getValue()
             var cleaned_content = current_value
                 .replace(/\s/g,'')
                 .replace(/\<p\>/g,'')
                 .replace(/\<\/p\>/g,'')
                 .replace(/\<\/br\>/g,'')
                 .replace(/\<br\>/g,'')
-                .replace(/&nbsp;/g,'')
-
-            return cleaned_content == ""
+                .replace(/&nbsp;/g,'');
+            return cleaned_content == "";
         },
-
-
         /*=========================SWITCHERS AND VALUE FETCHERS=================*/
-
-        //Returns True if conditions are met for markdown swtich
         switchable_to_markdown: function(ev) {
             /* show markdown if:
              *    - We have a MD tag. (e.g.  Html unedited, first load)
@@ -315,7 +292,8 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
               if (!is_empty && !has_md_source_tag ) {
                   console.log("FORBIDDEN EXECUTION BRANCH REACHED")
               } else {      
-              self.sw_html_to_mk();}
+                  self.sw_html_to_mk();
+              }
             }
             if (ev.currentTarget.id == "html") {
                 self.sw_mk_to_html()
@@ -331,10 +309,9 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
               this.$is_markdown = false;
               $(this.wysiwyg.el).parent().show();
         },
-
         sw_html_to_mk: function() {
               // markdown editor has problems with "falsy" values
-              if (!this.value){
+              if (!this.value) {
                   this.value = "" 
               }; 
               var markdown_value = this._getMarkdownValue(this.value);
@@ -352,12 +329,10 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
             return ''
         },
         _getHtmlValue: function(value) {
-            // Converts MD to html monodirectional converter
             if (!value) {
                 value='';
             }
             return marked(this._formatValue(value));
-
         },
     });
     field_registry.add("html_markdown", FieldHtmlMarkDown);