征求意见：在 Markdown 中包含代码片段的语法应该是什么？（来自外部文件）

发布于 2024-08-08 22:09:44 字数 644 浏览 6 评论 0原文

我最近一直在使用 Markdown。

我对 Markdown 最大的问题之一是 Markdown 没有在文档中包含文件的语法（相对于 listings LaTeX 包）。

我想扩展 Markdown 以支持将整个和部分文件作为代码片段包含在内。例如，它可能如下所示：

![:include src/foo/bar.rb](10-20)

这会将 bar.rb 第 10-20 行的内容作为 code 块放入我的文档中。理由是

文档可以随着代码的更改而更新。（与总是过时的复制和粘贴相比）
然后您可以对文档中的确切代码进行单元测试

我的问题是：

语法应该是什么？
这已经完成了吗，而我却错过了？

原文

I've been using Markdown recently.

One of my biggest problems with Markdown is that Markdown has no syntax for including files within a document (vs., say, the listings package for LaTeX).

I'd like to extend Markdown to support including whole and partial files as code snippets. For instance, it could look like this:

![:include src/foo/bar.rb](10-20)

and that would put the contents of bar.rb lines 10-20 into my document as a code block. The rationale is that

documentation can be updated as the code changes. (vs. copy and paste which always gets outdated)
you can then unit test the exact code that is in the documentation

My questions are:

What should the syntax be?
Has this already been done and I am missing it?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

白芷 2024-08-15 22:09:44

我更倾向于提出一种扩展 Markdown 语法的通用方法，然后使用它来提供对包含函数的支持。例如，您可以定义如下语法（我并不是真的建议这种特定语法，只是一个示例）：

[[command: arg arg arg...]]

..其中 command 指的是 markdown 解析器不理解但可以的命令回调其他东西来处理它。然后，您可以构建一个包含函数，该函数将与 Markdown 一起使用，但实际上并不是它的一部分。像这样的事情：

[[include: src/foo/bar.md]]

哦，如果你这样做，我可能不会提供包含部分文件的方法，至少不会使用行号 - 因为这意味着如果你更改了，你必须返回并编辑所有包含调用文档的长度，这实际上使重用变得更加困难（如果您能想出一种标记部分的方法，那可能会更好）。

I'd be more inclined to come up with a general means to extend Markdown syntax, and then use that to provide support for an include function. So for example you could define syntax like (I'm not really suggesting this particular syntax, just an example):

[[command: arg arg arg...]]

..where command refers to a command that the markdown parser doesn't understand, but can call back to something else to process it. Then you can build an include function that will work with markdown, but not actually be part of it. Something like:

[[include: src/foo/bar.md]]

Oh and if you do this, I'd probably not provide a means to include a partial file, at least not by using line numbers - as it means you have to go back and edit all the include calls if you change the length of the document, which actually makes reuse harder (if you could come up with a way to tag sections, that might work better).

回复收藏 0 原文

ぶ宁プ宁ぶ 2024-08-15 22:09:44

我通常倾向于看看是否可以以合理的方式使用现有语法。目前，该

    ![Example Photo](http://example.com/example.jpg)

语法及其相关语法用于在文本中包含图像。同样，

    +[Generic Heading](http://example.com/heading.txt)

    +[Local Heading](file:///dir/a/b/c/example.txt)

可用于包含文本。在这种情况下，方括号中的文本就像内联图像的 alt-text 属性：它包含所包含文件的简短的、人类可理解的描述。

使用 + 对我来说很直观：这意味着将此文件的内容添加到此处的此文档中。

I am generally inclined to see if things can be made to work withing existing syntax in a reasonable way. Currently, the

    ![Example Photo](http://example.com/example.jpg)

syntax and its relatives are used to include an image in the text. In a similar vein,

    +[Generic Heading](http://example.com/heading.txt)

    +[Local Heading](file:///dir/a/b/c/example.txt)

can be used to include text. In this case, the text in the square brackets is just like the alt-text attribute for inline images: It contains a short, human comprehensible description of the file being included.

Using + is intuitive to me: It means add the contents of this file to this document here.

回复收藏 0 原文