22-4-第九章 ArcGIS API for Python （4）

https://developers.arcgis.com/python/

9.7 Using Markdown in Jupyter Notebook

使用Jupyter Notebook的优势之一是, 可以在笔记本中添加代码以外的元素.。这些元素包括格式化文本、URL、图形、数学符号、HTML页面和各种类型的多媒体。这些元素可以使用一种称为Markdown单元的特殊类型的单元来添加。Markdown是一种轻量级标记语言，在数据科学社区中广泛使用。这是一个文本到HTML的转换工具，允许以纯文本编写，然后对HTML应用一些格式，以便在web浏览器中查看结果。标记语言类似于HTML，除了使用特殊的格式符号外，还使用相同的开始和结束标记，即。

将新单元格添加到笔记本时，默认情况下，单元格类型设置为“代码”，但可以通过选择单元格（即单元格的颜色为蓝色或绿色）并执行以下操作之一来更改它：（1）使用工具栏上的下拉选项将单元格类型从“Code”更改为“Markdown”；（2） 在顶部菜单上，单击“CELL”>“CELL TYPE”>“Markdown”；或（3）使用 m 键盘快捷键。

一旦单元格类型更改为“标记Markdown”，就可以输入文本并应用格式。格式包括使用标题heading、块引号block quotes、带编号或项目符号的列表numbered or bulleted lists以及斜体italic或粗体文本bold text。除了文本之外，还可以添加以下类型的元素：

Line breaks and horizontal lines 换行符和水平线
Python code used for illustration instead of execution用于说明而非执行的代码
URLs and other external links URL或者其他外部链接
Mathematical symbols and equations 数学符号和方程式
Tables 表
Images, videos, and animations 图像、视频和动画

标题是使用散列标记符号、数字符号和空格创建的。可以为其他标题级别添加额外的哈希标记符号。常规文本不使用任何特殊符号。当输入标题时，一些格式会立即显示出来，如图中所示。

但是，只有当运行单元格时，才会应用格式的分析呈现，如图所示。

要返回编辑“Markdown”单元格的内容，双击该单元格。

使用标记标签也可以实现相同的格式设置。例如，您可以使用

标记，即

标题

，而不是为标题1使用单个哈希标记符号。


使用特殊符号（如#和其他几个符号）时，后面必须有一个 空格才能识别该符号。如果没有空格，特殊符号将被视为常规文本的一部分。使用标记（如 <h1>）时，不使用空格。

粗体文本使用双星号（**）、双下划线（__）或<b>标记。
斜体文本使用单个星号（*）、单个下划线（_）或<i>标记。

项目符号列表可以通过使用短划线（-）、加号（+）或星号（*），后跟空格来创建。可以使用选项卡或两个空格创建嵌套列表。


可以创建一个编号列表，方法是从数字1开始，后跟一个点和一个空格，如图中所示。

常规文本格式可能有点棘手。例如，只需在一行文字后按Enter键不会产生换行符。然而，使用Enter键两次会开始一个新段落。可以使用两个空格或<br>标记作为换行符<br>标签是首选，因为这两个空格不清晰可见。


块引号使用右箭头括号（>）完成，也被称为“大于”符号，后面跟着一个可选空格，符号必须用在整段引号的每一行的开头。


可以使用三个连字符（---）、三个星号（***）或三个下划线（___）添加水平线。

Markdown中的外部链接使用一组方括号作为链接文本，后面是括号中的URL，如图中所示。

单击顶部菜单中的Edit>Insert Image，然后浏览到本地存储的文件，即可插入本地图像。插入图像后，文件名称前面会有一个感叹号（！）。


可以使用与URL等外部链接相同的语法插入外部图像，但带有感叹号的前缀除外。

这里的"title是pythonlogo"是鼠标落在图片上的文字显示

原书中有两个点号，应该是不对

也可以使用＜img＞标记插入图像。可以指定其他参数，例如宽度和高度。

<img src = https://www.python.org/static/community_logos/python-logo.png  width = 100  heigth = 100>

有时可能希望包含示例代码以进行说明，但不应执行代码本身。示例代码可以使用Markdown包含，方法是将一块代码封装在三个支持多行的后记号（```）中。可以通过在开场白后添加编程语言来添加语法高亮显示。对于内联代码，您可以使用单个反勾号或<code>标记。

一个例子
    ```Python
print("hello world")
    ```
一个例子使用换行符和code:<code>print("hello world")</code><br>
使用单个反引号作为例子: `print("hello world")`

在Markdown中使用代码只是说明一个概念或解释Python代码的一种方式，代码实际上并没有运行，也没有语法检查。

数学符号和表达式可以通过在文本两边加一个美元符号（$）来创建，如下所示：$数学符号或表达式$。数学符号和表达式的语法使用LaTeX，这是一种用于生成技术和科学文档的排版语言。Jupyter Notebook识别Markdown单元格中编写的LaTeX代码，并使用MathJax JavaScript库渲染符号。在Jupyter笔记本中使用LaTeX的能力是笔记本在数学和物理等领域流行的原因之一。
例如，下面的表达式创建了一个简单的内联公式，

公式示例：$V = \frac{{4\pi r^3 }}{3}$

数学公式可以使用$$

公式示例：$$V = \frac{{4\pi r^3 }}{3}$$

因为Markdown使用许多特殊符号进行格式化，所以当您需要这些字符时可以使用反斜杠来生成文字字符。例如，以下代码创建星号和美元符号，如图所示。

\* axxecdfwev<br>
\# excef

所示示例仅涵盖使用Markdown单元格的一些关键元素，有许多在线资源更详细地介绍了Markdown for Jupyter Notebook的使用。Markdown提供了一种增强笔记本的好方法，因为除了Python代码本身之外，您还可以在代码中添加解释，提供背景信息，并包括可视化。
Markdown有几个不同的“flavors”，它们在语法和功能上略有不同。例如，GitHub平台使用了一种叫做GitHub Flavors Markdown（GFM）的Markdown方言，这与“标准”Markdown不同。Jupyter在很大程度上遵循GFM，但略有不同。

以下图片展示了ArcGIS API for Python帮助页面上发布的一个名为“2015年钦奈洪水-地理分析”的示例笔记本。笔记本以2015年发生的库德事件的一些背景信息开始，随后是降雨和洪水的可视化和分析，示例说明了在单个笔记本中使用Markdown单元格和代码单元格。


使用Jupyter Notebook的好处之一是，您可以提供在单个文档中并排运行工作流和文档的代码。用户可以阅读使用Markdown编写的文档，同时与代码交互。