Package: dash-down
Thedash-downpackage provides tools to render markdown files into Plotly Dash component trees. Besides standard markdown syntax, a custom interpretation of thedirective syntax extensionmakes it possible to embed Dash code blocks and/or applications (including callbacks). For a live demo, please take look at thedash-extensionsdocumentation.Getting startedMake sure that you have setuppoetry. Then runpoetry installto install dependencies.Running the examplepoetry run python example.pyRunning the testspoetry run pytestCustom contentCustom content is rendered via the markdowndirective syntax extension. A directive has the following syntax,.. directive-name:: directive value
   :option-key: option value
   :option-key: option value

   full featured markdown text herewhere thedirective-nameis mandatory, while thevalue, theoptions(specified as key value pairs), and thetextare optional.What directives are bundled?Currently, the bundled directives areapi-doc- a directive for rendering api documentation for a componentdash-proxy- a directive for rendering dash apps (including interactivity)How to create custom directives?The easiest way to create a custom directive is to create a function with the following signature,fromboximportBoxfromdash_extensions.enrichimportDashBlueprintdefdirective_name(value:str,text:str,options:Box[str,str],blueprint:DashBlueprint):""":param value: the directive value (optional):param text: the markdown text (optional):param options: a Box object containing all key value pairs (optional):param blueprint: the DashBlueprint of the resulting Dash component tree, used e.g. for callback registration:return: a Dash component"""...Say, we want to make a new directive that yields a plot of theirisdataset. The code would then be along the lines of,importplotly.expressaspxfromboximportBoxfromdash_extensions.enrichimportdcc,DashBlueprintdefgraph(value:str,text:str,options:Box[str,str],blueprint:DashBlueprint):df=getattr(px.data,options.dataset)()fig=px.scatter(df,x=options.x,y=options.y)returndcc.Graph(figure=fig)With this directive defined, it is now possible to create a graph similar tothe one in the Dash docswith the following syntax,.. graph::
   :dataset: iris
   :x: sepal_width
   :y: sepal_lengthTo render a markdown file using the new, shiny directive, the syntax would be,fromdash_extensions.enrichimportDashProxyfromdash_down.expressimportmd_to_blueprint_dmc,GITHUB_MARKDOWN_CSS_LIGHT...blueprint=md_to_blueprint_dmc('path_to_your_md_file',directives=[graph])app=DashProxy(blueprint=blueprint,external_stylesheets=[GITHUB_MARKDOWN_CSS_LIGHT])if__name__=='__main__':app.run_server()A working example is bundled in the repo (seeexample_custom_directive.py).How to customize the layout of the rendered blueprint?The layout of the blueprint returned by the renderer can be customized by passing a custom app shell via theshellkeyword of themd_to_blueprint_dmcfunction. A working example is bundled in the repo (seeexample_code_renderer.py).Per default, the app shell is aDivelement withclassName="markdown-body". This class makes it possibly to use GitHub CSS for styling.How to customize the way code is rendered with the DashProxyDirective?The layout of the Dash apps rendered via theDashProxyDirectivecan be customized via thedash_proxy_shellkeyword of themd_to_blueprint_dmcfunction. A working example is bundled in the repo (seeexample_code_renderer.py).Per default, the app shellDivelement with the code rendered as the first child and the resulting app rendered as the second.How to customize the markdown rendering itself?Make a subclass ofDashMantineRenderer(orDashHtmlRenderer, if you prefer to start from raw HTML) and override the render function(s) for any element that you want to change. A good place to start would be to look at theDashMantineRendererclass itself for inspiration.