We are trying to implement an automatic markdown generator for an easily maintainable documentation.
When mentioning a variable's type, we would like to prefix it with ? when it is nullable, use backticks around it and add a link to its description. For example: `?[Article](#article)`.
However, the backticks break the link syntax because of the overlap. We use `?`[`Article`](#article) instead to make the link works but it creates a space between ? and Article as follow: ?Article.
Is it possible to make it look like ?Article with a link on Article only?
I just tested this out and discovered that there is no space between ? and Article. What appears to be a space is simply GitHub's styling of two <code> blocks up against each other.
Wrapping the whole thing in backticks won't work because backticks indicate code, and Markdown treats the contents as if they are a code sample where you want to show the source.
The best workaround I can find is to use <code> tags directly:
<code>?[Article](https://stackoverflow.com/)</code>
On both GitHub and Stack Overflow this renders like so:
?Article
(I have used a link to Stack Overflow as the link target here simply so we get a rendered link as an example. I expect that #article will work equally well in your environment.)
In my opinion this is even a reasonable way of doing what you want. Markdown's backticks compile to <code> tags, and inline HTML code is expressly permitted by Markdown:
For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
Related
I'm trying to figure out how to modify an XML file with NSIS. So I'm trying to learn how to use the XML plugin. The examples on the forum page often use the format ${plugin::command} like:
${xml::LoadFile}
The documentation gives no indication that you need the dollar sign and curly braces. As I understand it, just plugin::command will do. So I've been trying to figure out what that syntax means.
The documentation says a $ is for variables and the {} are for code blocks, but I can't find anything about what it means when they're used together. My Internet searches have revealed that it's used for something called template literals in JavaScript. But what does it mean in NSIS?
EDIT: I should mention that the NSIS documentation does show examples of this syntax, especially in the Predefines section, but it still doesn't explain what the syntax means in general.
EDIT: Okay, now I see that the syntax is for the compiler to replace things using !define and !macro. But... what about this specific case? Is it valid to use colons in such a symbol? Why are some people writing ${xml::LoadFile}and some people just writing xml::LoadFile?
It's a !define. There is a header file for this plugin that defines it. The plugin probably needs to do more than one thing, so they wrapped a few lines together with a define that inserts a macro. Either that or it has some default parameters for the plugin call. Either way, it's trying to save you some typing with this syntax.
Documentation clearly states that code block inside sentence marked using `backticks`.
```Language_Name_Here
For for multi-line block we can use triple backticks
```
But how I can specify language name for embedded block of code? Like <XmlNode Prop="Value" />? I just want to prettify my readme.md to look like this inside sentence:
<XmlNode Prop="Value" />
Looks like the same question related to stackowerflow itself. "language-all" comment is not working for embedded code blocks.
It does not appear to me that this is possible. The spec refers to this as an info string for the code fence (aka fenced code block). The spec for code spans (inline code like you are asking about) does not support info strings.
Does anybody know how to maintain symbols in markdown internal links?
For example:
[A](#A) works fine
[A and B](#a-and-b) works fine
...whereas:
[A/B](#a-b) does not work
[A-B](#a-b) does not work
Thanks for your help!
I remember running into this problem too.
[A/B](#ab) should work, instead of using [A/B](#a-b).
A / character is considered a non-character in this case, but when it is not part of a word (ex. Movies / Shows / Videos) then it needs to be treated like an empty word:
[Movies / Shows / Videos](#movies--shows--videos)
I'm not sure how [A-B](#a-b) isn't working for you, because it should work?
I recommend checking here, every now and then, for additional information being added to the conversation around Github Markdown Heading Anchors: https://gist.github.com/asabaylus/3071099
This is also known as github-slugging or GitHub-style slugging.
After copying and pasting your code into my markdown editor, Mou, I see no issues with either statement. In fact, I copied the link as well, and it keeps the symbols you want.
Perhaps this is an issue with your version of markdown or your editor. If you are using a different flavor of markdown, like github, I'd be sure to specify that with tags as that may be your issue. Basic markdown should handle escaping characters though unless it's a bracket. If you want some helpful information, please visit this stack overflow thread: Escaping Brackets
I'm looking for a way to generate and insert header comment blocks above my functions in Emacs (in any mode), with the default contents of the comment automatically based on the function's signature (i.e. the correct number of #param place-holders).
Doxymacs is a nice candidate. But I prefer another way works without the necessary libs. Can anyone recommend some others ways for adding smart comments for functions in Emacs? Thanks.
Edit:
Now I found this: http://nschum.de/src/emacs/doc-mode/, but it seems that it does not work well after I require it into my .emacs and add hook for js-mode. Doesn't it support js functions ?
I don't know of any general-purpose approach.
Csharp-mode has a defun that is bound to / , which tries to generate comments appropriate for C#. The way it works: Every time you type a slash, it looks to see if it is the third slash in a row. (In C#, three slashes are used to denote comments that produce documentation). If it is the third slash, then it looks at the surrounding text and inserts a comment skeleton or fragment that is appropriate.
It is not generalized in any way to support javascript or other language syntaxes. But you might be able to build what you want, if you start with that.
here's the excerpt:
http://pastebin.com/ATCustgi
I've used doxymacs in the past and I've found it useful
http://doxymacs.sourceforge.net/
As you can see, Markdown syntax isn't applied to my blog.
This is my GitHub
I am using the 'minimal-mistake' theme.
One expectation is that in the process of applying the 'minimal-mistakes' theme to my blog, I didn't clone all the files in the theme, but added only the parts I needed.
Could this be a problem?
Put a space after any hashes you are using for a headline.
Instead of
###Title
write
### Title
This has a secondary benefit of being considerably more readable in its source form, which was a design goal for Markdown:
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.