{"author":"Md. Jahidul Hamid","author_email":"jahidulhamid@yahoo.com","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","Intended Audience :: Information Technology","License :: OSI Approved :: BSD License","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 2","Programming Language :: Python :: 3","Topic :: Text Processing :: Filters","Topic :: Text Processing :: Markup"],"description":"[![Build Status](https://travis-ci.org/neurobin/mdx_include.svg?branch=release)](https://travis-ci.org/neurobin/mdx_include)\n\nInclude extension for Python Markdown. It lets you include local or remote (downloadable) files into your markdown at arbitrary positions. \n\nThis project is motivated by [markdown-include](https://github.com/cmacmackin/markdown-include) and provides the same functionalities with some extras.\n\nInclusion for local file is by default recursive and for remote file non-recursive. You can change this behavior through configuration.\n\nYou can include part of the file by slicing according to line/column number.\n\nFile/Downloaded contents are cached, i.e if you include same file multiple times in multiple places, they won't be read/downloaded more than once. This behavior can also be changed with configuration.\n\nCircular inclusion by default raises an exception. You can change this behavior to include the affected files in non-recursive mode through configuration.\n\n**You should not use markdown-include along with this extension, choose either one, not both.**\n\n# Syntax\n\n1. **Simple:** `{! file_path_or_url !}`\n2. **With explicit encoding:** `{! file_path_or_url | encoding !}`\n3. **With recurs_state on:** `{!+ file_path_or_url !}` or `{!+ file_path_or_url | encoding !}`. This makes the included file to be able to include other files. This is meaningful only when recursion is set to `None`. If it is set to `False`, this explicit recurs_state defintion can not force recursion. This is a depth 1 recursion, so you can choose which one to recurs and which one to not.\n4. **With recurs_state off:** `{!- file_path_or_url !}` or `{!- file_path_or_url | encoding !}`. This will force not to recurs even when recursion is set to `True`.\n5. **Applying indentation** `{!> file_path_or_url!}`. This will apply the indentation found in the include line before the include for all the lines in the included file.\n6. **Escaped syntax:** You can escape it to get the literal. For example, `\\{! file_path_or_url !}` will give you literal `{! file_path_or_url !}` and `\\\\\\{! file_path_or_url !}` will give you `\\{! file_path_or_url !}`\n7. **File slice:** You can slice a file by line and column number. The syntax is `{! file_path [ln:l.c-l.c,l.c-l.c,...] !}`. No spaces allowed inside file slice syntax `[ln:l.c-l.c,l.c-l.c,]`. See more detals in [File slicing section](#file-slicing).\n\n\n**General syntax:** `{!recurs_state apply_indent file_path_or_url [ln:slice_syntax] | encoding !}`\n\n> The spaces are not necessary. They are just to make it look nice :) . No spaces allowed between `{!` and recurs_state (`+-`). If apply indentation is specified then it must follow recurse_state immediately or the `{!` if recurse_state is not specified. \n\n\n## You can change the syntax!!!\n\nIf you don't like the syntax you can change it through configuration.\n\nThere might be some complications with the syntax `{!file!}`, for example, conflict with `markdown.extensions.attr_list` which uses `{:?something}`. As the `:` is optional, a typical problem that occurs is this one:\n\n```md\nA paragraph\n{!our syntax!}\n```\nwould produce:\n\n```html\n

A paragraph

\n```\n\nIf you really want to avoid this type of collision, find some character sequence that is not being used by any extension that you are using and use those character sequences to make up the syntax.\n\n[See the configuration section for details](#configuration)\n\n\n# Install\n\nInstall from Pypi:\n\n```bash\npip install mdx_include\n```\n\n# Usage\n\n```python\ntext = r\"\"\"\nsome text {! test1.md !} some more text {! test2.md | utf-8 !}\n\nEscaping will give you the exact literal \\{! some_file !}\n\nIf you escape, then the backslash will be removed.\n\nIf you want the backslash too, then provide two more: \\\\\\{! some_file !}\n\"\"\"\nmd = markdown.Markdown(extensions=['mdx_include'])\nhtml = md.convert(text)\nprint(html)\n```\n\n**Example output:**\n\n(*when test1.md contains a single line `**This is test1.md**` and test2.md contains `**This is test2.md**`*)\n\n```html\n

some text This is test1.md some more text This is test2.md

Escaping will give you the exact literal {! some_file !}

If you escape, then the backslash will be removed.

If you want the backslash too, then provide two more: \\{! some_file !}

\n```\n\n\n# Configuration\n\nConfig param | Default | Details\n------------ | ------- | -------\n`base_path` | `.` | The base path from which relative paths are normalized.\n`encoding` | `utf-8` | The file encoding.\n`allow_local` | `True` | Whether to allow including local files.\n`allow_remote` | `True` | Whether to allow including remote files.\n`truncate_on_failure` | `True` | Whether to truncate the matched include syntax on failure. False value for both allow_local and allow_remote is treated as a failure.\n`recurs_local` | `True` | Whether the inclusions are recursive on local files. Options are: `True`, `False` and `None`. `None` is a neutral value with negative default and overridable with recurs_state (e.g `{!+file!}`). `False` will permanently prevent recursion i.e you won't be able to override it with the recurs_state. `True` value is overridable with recurs_state (e.g `{!-file!}`).\n`recurs_remote` | `False` | Whether the inclusions are recursive on remote files. Options are: `True`, `False` and `None`. `None` is a neutral value with negative default and overridable with recurs_state (e.g `{!+file!}`). `False` will permanently prevent recursion i.e you won't be able to override it with the recurs_state. `True` value is overridable with recurs_state (e.g `{!-file!}`).\n`syntax_left` | `\\{!` | The left boundary of the syntax. (Used in regex, thus escaped `{`).\n`syntax_right` | `!\\}` | The right boundary of the syntax. (Used in regex, thus escaped `}`).\n`syntax_delim` | `\\\\|` | The delimiter that separates encoding from path_or_url. (Used in regex, thus escaped `\\|`).\n`syntax_recurs_on` | `+` | The character to specify recurs_state on. (Used in regex).\n`syntax_recurs_off` | `-` | The character to specify recurs_state off. (Used in regex).\n`syntax_apply_indent`| `\\>`| The character which stands for applying indentation found before the include for the lines included from the files.\n`content_cache_local` | `True` | Whether to cache content for local files.\n`content_cache_remote` | `True` | Whether to cache content for remote files.\n`content_cache_clean_local` | `False` | Whether to clean content cache for local files after processing all the includes\n`content_cache_clean_remote` | `False` | Whether to clean content cache for remote files after processing all the includes\n`allow_circular_inclusion` | `False` | Whether to allow circular inclusion. If allowed, the affected files will be included in non-recursive mode, otherwise it will raise an exception.\n`line_slice_separator` | `['','']` | A list of lines that will be used to separate parts specified by line slice syntax: 1-2,3-4,5 etc.\n`recursive_relative_path` | `False` | Whether include paths inside recursive files should be relative to the parent file path\n\n## Example with configuration\n\n```python\nconfigs = {\n 'mdx_include': {\n 'base_path': 'mdx_include/test/',\n 'encoding': 'utf-8',\n 'allow_local': True,\n 'allow_remote': True,\n 'truncate_on_failure': False,\n 'recurs_local': None,\n 'recurs_remote': False,\n 'syntax_left': r'\\{!',\n 'syntax_right': r'!\\}',\n 'syntax_delim': r'\\|',\n 'syntax_recurs_on': '+',\n 'syntax_recurs_off': '-',\n 'syntax_apply_indent': r'\\>',\n },\n }\n\ntext = r\"\"\"\nsome text {! some_file !} some more text {! some_more_file | utf-8 !}\n\nEscaping will give you the exact literal \\{! some_file !}\n\nIf you escape, then the backslash will be removed.\n\nIf you want the backslash too, then provide two more: \\\\\\{! some_file !}\n\"\"\"\nmd = markdown.Markdown(extensions=['mdx_include'], extension_configs=configs)\nhtml = md.convert(text)\nprint(html)\n```\n\n# File slicing\n\nYou can include part of the file from certain line/column number to certain line/column number.\n\nThe general file slice syntax is: `[ln:l.c-l.c,l.c-l.c,...]`, where l is the line number and c is the column number. All indexes are inclusive.\n\n**Examples:**\n\nSlice | Details\n----- | -------\n`[ln:1-4]` | line 1 to 4 (both inclusive)\n`[ln:1.2-3.4]` | character 2 in line 1 to character 4 in line 3\n`[ln:2-]` | line 2 to all of the rest\n`[ln:-3]` | Last line to 3rd line (reversion)\n`[ln:6-2]` | 6th line to 2nd line (reversion)\n`[ln:2.9-2.2]` | From 9th character of line 2 to 2nd character of line 2 (string reverse)\n`[ln:.3-.10]` | Slice along the column from every row, from 3rd character to 10th character\n`[ln:2]` | line 2 only\n`[ln:e]` | last line\n\nMultiple slicing can be done by adding more slice expressions with commas (s`,`). In this case, a separator (default is two newlines) is inserted between each slice. For example, with slice expression `1-2,4-9`, two newlines will be inserted between the lines 1-2 and 4-9.\n\nMore details on the [rcslice doc](https://github.com/neurobin/rcslice)\n\n# Manual cache control\n\nThe configuration gives you enough cache control, but that's not where it ends :). You can do manual cache cleaning instead of letting the extension handle it for itself. First turn the auto cache cleaning off by setting `content_cache_clean_local` and/or `content_cache_clean_remote` to `False` (this is default), then call the cache cleaning function manually on the markdown object whenever you want:\n\n```python\nmd.mdx_include_content_cache_clean_local()\nmd.mdx_include_content_cache_clean_remote()\n```\n\nYou can also get the internal cache dictionary and make inplace modification (e.g cleaning a specific cache for a specific file/URL, or even modify the cached content):\n\n```python\nlocal_cache_dict = md.mdx_include_get_content_cache_local()\nremote_cache_dict = md.mdx_include_get_content_cache_remote()\n```\n\n# How circular inclusion works\n\nLet's say, there are three files, A, B and C. A includes B, B includes C and C inclues A and we are doing recursive include.\n\nIf circular inclusion is not allowed in the config i.e if `allow_circular_inclusion` is `False` (which is the default) then it will raise an exception.\n\nIf `allow_circular_inclusion` is set to `True`, then it will work like this:\n\n1. A and B will be normally included\n2. B includes C normally too\n3. C includes A which is a circular inclusion (`C>A>B>C>A>B>C...`). Thus A will be included in non-recursive mode as `allow_circular_inclusion` is set to `True` i.e C will include A literally without parsing A anymore.\n\n# An example of including a gist\n\nThe following markdown:\n\n\n Including a gist:\n \n ```python\n {! https://gist.github.com/drgarcia1986/3cce1d134c3c3eeb01bd/raw/73951574d6b62a18b4c342235006ff89d299f879/django_hello.py !}\n ```\n\n\nwill produce (with fenced code block enabled):\n\n```html\n

Including a gist:

# -*- coding: utf-8 -*-\n\n# Settings\nfrom django.conf import settings\n\n\nsettings.configure(\n    DEBUG=True,\n    SECRET_KEY='secretfoobar',\n    ROOT_URLCONF=__name__,\n    MIDDLEWARE_CLASSES=(\n        'django.middleware.common.CommonMiddleware',\n        'django.middleware.csrf.CsrfViewMiddleware',\n        'django.middleware.clickjacking.XFrameOptionsMiddleware',\n    )\n)\n\n\n# Views\nfrom django.http import HttpResponse\nfrom django.conf.urls import url\n\n\ndef index(request):\n    return HttpResponse('<h1>Hello Word</h1>')\n\n# Routes\nurlpatterns = (\n    url(r'^$', index),\n)\n\n\n# RunServer\nif __name__ == '__main__':\n    from django.core.management import execute_from_command_line\n    import sys\n\n    execute_from_command_line(sys.argv)\n\n

\n```\n\n\n","description_content_type":"text/markdown","docs_url":null,"download_url":"","downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/neurobin/mdx_include","keywords":"markdown include local remote file","license":"BSD","license_expression":null,"license_files":null,"maintainer":"","maintainer_email":"","name":"mdx-include","package_url":"https://pypi.org/project/mdx-include/","platform":null,"project_url":"https://pypi.org/project/mdx-include/","project_urls":{"Homepage":"https://github.com/neurobin/mdx_include"},"provides_extra":null,"release_url":"https://pypi.org/project/mdx-include/1.4.2/","requires_dist":["Markdown (>=2.6)","rcslice (>=1.1.0)","cyclic"],"requires_python":"","summary":"Python Markdown extension to include local or remote files","version":"1.4.2","yanked":false,"yanked_reason":null}

Dependencies of mdx-include (3).
Dependency	Optional
cyclic	false
Markdown	false
rcslice	false

Package search

mdx-include

project_urls

Dependencies

All package metadata

Releases