Package: markdown-xblock
Markdown XBlockBased on theHTML XBlock by OpenCraftIntroductionThis XBlock allows course authors to create and edit course content in Markdown
and displays it as HTML.Installation withTutorYou may install the markdown-xblock to your Tutor environment by adding it to theOPENEDX_EXTRA_PIP_REQUIREMENTSlist inconfig.yml:OPENEDX_EXTRA_PIP_REQUIREMENTS:
- markdown-xblock==1.4.0Or, if you prefer to install directly from Git:OPENEDX_EXTRA_PIP_REQUIREMENTS:
- git+https://github.com/citynetwork/markdown-xblock.git@v1.4.0For additional information, please refer to the officialdocumentation.The minimum supported Python version is 3.8.To enable this block, add"markdown"to the course's advanced module list.
The optionMarkdownwill appear in the advanced components.Once you've added a newMarkdowncomponent to your course, you can also add custom CSS classes to the component
by selectingEDIT/Settingsand adding to theclasseslist (Note: use double quotes" "). Example:["custom-css-class-1", "custom-css-class-2"]TheMarkdownblock usesmarkdown2to translate the content into HTML,
by default the following extras are included:"code-friendly""fenced-code-blocks""footnotes""tables""use-file-vars"ConfigurationIt is possible to configure moreextras, by
adding to the extras list under"markdown"key inXBLOCK_SETTINGSin yourTutor pluginthat patchesopenedx-common-settingsBy default, thesafe_modeformarkdown2library is enabled and set
toreplace, which means that writing inline HTML is not allowed and
if written, all tags will be replaced with[HTML_REMOVED]. You can
also setsafe_modetoescape, which only replaces<,>and&with&lt;,&gt;and&amp;. To disable safe mode altogether and
allow inline HTML, you'll need to setsafe_modetoFalseorNoneinXBLOCK_SETTINGS. Please note that settingsafe_modeto the
empty string ('')alsodisables safe mode.Example (YAML plugin):name: markdown
version: 1.0.0
patches:
  openedx-common-settings: |
    XBLOCK_SETTINGS["markdown"] = {
        "extras": [
            "code-friendly",
            "fenced-code-blocks",
            "footnotes",
            "tables",
            "header-ids",
            "metadata",
            "pyshell",
            "smarty-pants",
            "strike",
            "target-blank-links",
            "use-file-vars",
            "wiki-tables",
            "tag-friendly"
        ],
        "safe_mode": "escape"
    }Usage notesImagesTo include images in your markdown content, use the standard
Markdown inline image syntax. Your course images will normally live in
thestatic/imagesdirectory, relative to the root of your course, so
you would include an image like this:![alt text for example image](/static/images/example.png)The XBlock will then mangle your image reference into a static asset
reference.LinksIf Markdown XBlock content contains links to another course, and your
platform is configured with the XBlock's safe mode enabled, a link
like[link text](https://example.com/courses/course-v1:Org+Class+Version/about)will, when rendered, turn its+characters into whitespace. That
isn't actually wrong, because both+and the%20escape sequence
in URLs are meant to represent whitespace, yet Open edX uses the+character to mean somethingotherthan whitespace, and that's a bit
of a problem.To preserve Open edX course URL references, please explicitly encode
the+character as%2B, like so:[link text](https://example.com/courses/course-v1:Org%2BClass%2BVersion/about)DevelopmentIf you'd like to develop on this repo inTutor, follow the steps described in thedocumentation.Running testsThe testing framework is built ontox. After installing tox, you can runtoxfrom your Git checkout of this repository.To throw away and rebuild the testing environment, run:$tox-rFor running PEP-8 checks only:$tox-eflake8