Markdown processing and displaying

Embed markdown file

I often embed markdown files here via display(Markdown(text)) (see embed_markdown_file). This is useful when I want to state the same thing multiple times (e.g. definitions) because I can write the statement in one location and it will automatically be updated whenever I make changes to the statement (e.g. fixing errata).

One obstruction to this is that links in the markdown files cannot be expected to link to where I want them to - if I were to make links to (local) notebook files during editing, then the links will not link to webpages when I upload the website.

The embed_markdown_file method circumvents this obstruction - it allows me to choose whether the links will lead to (local) notebooks or the website. I will format links in the markdown files without specifying the precise destinations, e.g. [limit](limit_of_a_function_at_a_point) will show the text limit and link to either a (local) notebook limit_of_a_function_at_a_point.ipynb or a webpage limit_of_a_function_at_a_point.html in the website.

Note The notebook files and the corresponding html files that are generated during nbdev_build_docs need to have the same name, e.g. function.ipynb needs to generate function.html.

find_links_in_markdown_text[source]

find_links_in_markdown_text(text)

Returns ranges in the markdown text string where links occur.

Parameters

  • text - str

Returns

  • list of tuples. Each tuple is of the form (a,b) where text[a:b] is a markdown link.

Examples

sample_text = '123hi [thing](link) blah'
sample_range = find_links_in_markdown_text(sample_text)
assert len(sample_range) == 1
assert sample_text[sample_range[0][0]:sample_range[0][1]] == '[thing](link)'

link_with_anchor(link_name, destination='website')

Formats link so that the file extension comes before the pound sign of the anchor.

Parameters

  • link_name - str
    • Should not be empty. Should be of the form 'link' or 'link#anchor', i.e. should not have surrounding parentheses. Does not have a file extension, e.g. '.html' or '.ipynb'.
  • destination - 'website' or 'notebook'.

Returns

  • The same as link_name, except with the appropriate file extension added in before the anchor, if any and with the parentheses removed.

Examples

sample_link_name = 're#re.split'
sample_output = link_with_anchor(sample_link_name, destination ='website')
assert sample_output == 're.html#re.split'
sample_output = link_with_anchor(sample_link_name, destination ='notebook')
assert sample_output == 're.ipynb#re.split'

sample_link_name = 'hi#'
sample_output = link_with_anchor(sample_link_name, destination ='website')
assert sample_output == 'hi.html#'

get_formatted_markdown_link(unformatted_link, destination='website')

Formats markdown styled link string.

Parameters

  • unformatted_link - str
    • Of the form [text](link).
  • destination - 'website' or 'notebook'.

Returns

  • str, of the form [text](link.html) or [text](link.ipynb) depending on destination.

Examples

sample_link = '[function](function)'
sample_formatted_link = get_formatted_markdown_link(sample_link, destination='website')
assert sample_formatted_link == '[function](https://hyunjongkimmath.github.io/mathbook/function.html)'
sample_formatted_link = get_formatted_markdown_link(sample_link, destination='notebook')
assert sample_formatted_link == '[function](function.ipynb)'

sample_link = '[limit](limit#limit_of_a_function_at_a_point)'
sample_formatted_link = get_formatted_markdown_link(sample_link, destination='website')
assert sample_formatted_link == '[limit](https://hyunjongkimmath.github.io/mathbook/limit.html#limit_of_a_function_at_a_point)'
sample_formatted_link = get_formatted_markdown_link(sample_link, destination='notebook')
assert sample_formatted_link == '[limit](limit.ipynb#limit_of_a_function_at_a_point)'

replace_all_links_with_formatted_links(text, destination='website')

Returns a modification of text with all links formatted.

Parameters

  • text - str
  • destination - 'website' or 'notebook'.

Footnotes

I usually use footnotes in markdowns to make citations or to indicate notations. An example of the latter kind of footnotes is "$\operatorname{Pic}(X)$ denotes the Picard group of the variety $X$", where the term "Picard group" is linked to a page containing a definition of the term.

Although this can be time consuming for the writer to put together, the reader does not have to spend a great effort to figure out where the notation is introduced. This is particularly nice especially there is much notation exclusive to the writer's field or niche.

The writer also can quickly remind themselves of the notation whenever necessary. This is particularly useful when the writer is learning something new for the first time.

Note that jupyter notebook and the webpages treat footnotes differently. On the one hand, jupyter seems to treat footnotes as links by default. This thus has the same problem as that in the section above. In other words, I also have to make sure that footnotes link to the correct location. On the other hand, the webpages treat the footnotes as text.

find_footnotes_in_markdown_text[source]

find_footnotes_in_markdown_text(text)

Returns ranges in the markdown text string where footnotes occur.

Parameters

  • text - str

Returns

  • list of tuples. Each tuple is of the form (a,b) where text[a:b] is a markdown footnote.

Examples

sample_text = 'some stuff[^1][^2]\n[^1]:link#do\n[^2]:other_link'
sample_ranges = find_footnotes_in_markdown_text(sample_text)
assert len(sample_ranges) == 2
a, b = sample_ranges[0]
c, d = sample_ranges[1]
assert sample_text[a:b] == "[^1]:link#do"
assert sample_text[c:d] == "[^2]:other_link"

replace_all_footnotes_with_formatted_footnotes[source]

replace_all_footnotes_with_formatted_footnotes(text, destination='website', origin='website')

Returns a modification of text with all footnote links formatted.

The replace_all_footnotes_with_formatted_footnotes function depends on both the destination and origin the the origin - the place where the "markdown" document is being read.

  • if destination is 'website', then the footnote should be the url of the webpage.
  • if origin is 'notebook' and destination is 'notebook', then the footnote should be the path to the destination notebook.
  • I am not currently implementing the other case, i.e. if origin is 'website' and destination is 'notebook'.

Parameters

  • text - str
  • destination - 'website' or 'notebook'.
  • origin - 'website' or 'notebook'. If this is

Examples

sample_text = 'some stuff[^1][^2]\n[^1]:link#do\n[^2]:other_link'
replace_all_footnotes_with_formatted_footnotes(sample_text, destination='website')

'some stuff[^1][^2]\n[^1]:https://hyunjongkimmath.github.io/mathbook/link.html#do\n[^2]:https://hyunjongkimmath.github.io/mathbook/other_link.html'

Final method

embed_markdown_file[source]

embed_markdown_file(file_path, display_file_link=False, destination='website', origin='website')

Embed markdown file content into ipynb.

Parameters

  • file_path - Path-like
  • display_file_link - bool
    • If True, then displays a link to an edit mode ipynb for the markdown file at file_path. This should only be set to True inside an ipynb environment such as jupyter.
  • destination - 'website' or 'notebook'
  • origin - 'website' or 'notebook'

Examples

embed_markdown_file('definition.function_defined_near_a_point.md', destination='notebook', origin='notebook')

[(31, 86), (94, 121), (140, 179), (267, 298), (340, 373), (393, 442), (454, 483)]

Let $f: D \to \mathbb{R}$ be a real valued function from a subset $D$ of the set of real numbers $\mathbb{R}$.

We say that $f$ is defined near $a \in \mathbb{R}$ if there is some interval $I$ such that

  1. $a \in I$ and
  2. $f$ is defined on $I \setminus \{a\}$1,2, i.e. the domain $D$ of $f$ contains $I \setminus \{a\}$.

  1. notation.basic.ipynb#$\setminus$↩

  2. notation.basic.ipynb#$\{a\}$↩