Currently I'm using this markdown text inside the README.md file of a project on GitHub:
See the docs of [testthat][3] on how to write unit tests.
Links
-----
- http://www.rstudio.com/products/rpackages/devtools/
- https://github.com/hadley/testthat
- http://r-pkgs.had.co.nz/tests.html
---
[1]: http://www.rstudio.com/products/rpackages/devtools/
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html
I don't like this duplication, but I don't see what choice I have. If I remove the explicit bullet point lists, then GitHub won't display the reference links. If I remove the reference links, then GitHub shows the bullet point list (of course), but the embedded links like "testthat" above don't work.
Is there a better way than duplicating? What am I missing?
Inspired by #mb21, I suppose this would be the right way to do it:
See the docs of [testthat][2] on how to write unit tests.
Links
-----
- [RStudio Devtools][1]
- [testthat][2]
- [More unit test examples][3]
[1]: https://stackoverflow.com/users/214446/mb21
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html
That is, it's not a good practice to include links verbatim and without a meaningful title. I should keep the link URLs only in the reference links section at the bottom, and in the bullet point list use meaningful titles.
When you view this on GitHub, the URLs shouldn't really matter, and if you really want to know you can move the mouse over. When you view this in plain text, now the links have meaningful titles, which is useful additional information about the URLs.
I'd write that as follows:
See the docs of [testthat][1] on how to write unit tests.
Links
-----
- [RStudio Devtools](http://www.rstudio.com/products/rpackages/devtools/)
- [Testthat](https://github.com/hadley/testthat)
- [Tests][1]
[1]: http://r-pkgs.had.co.nz/tests.html
Did that answer your question? If not, you'll have to clarify it.
An answer from 8 years in the future!
The answer to your question will depend on what your Markdown parser supports. Nowadays, most parsers support CommonMark (plus some flavouring). However, don't take this for granted and double check it. If CommonMark is not supported, try using the "vanilla" Markdown syntax as described below. Just be aware that the "vanilla" Markdown specification is flawed and may result in broken links (by design, almost).
Using CommonMark
If you can guarantee that your Markdown parser supports CommonMark, then you can do it in a simple way:
Writing unit tests is explained in the [Unit Testing] website
[Unit Testing]: https://unittesting.somedomain.com
In the Links section of the CommonMark specification (currently at version 0.30) you see that a "link" is composed of a link text, link destination and a title and each one has its own syntax and quirks. For example, if the link destination contains spaces, you need to wrap it in <angled brackets>, or if your link text is some kind of code, you're allowed to write
[`AwesomeClass`](<../docs/awesome class.md>]
Note:
In this section I am using the CommonMark syntax, so you can click the
"Edit" button to see the syntax that I used for a "real" example.
Using vanilla Markdown
The vanilla Markdown specification simply requires an extra set of angled brackets with nothing in between, as described in the links section.
Writing unit tests is explained in the [Unit Testing][] website
[Unit Testing]: https://unittesting.somedomain.com
Note
And in this section I've only used vanilla Markdown syntax. Stack Overflow's Markdown parser supports both CommonMark and vanilla Markdown. This is not by accident, since CommonMark intends to be compatible with the original specification (wherever possible!). Stack Overflow do state that they use the CommonMark spec in their Markdown help page.
Tl;dr
See the docs of [`testthat`] on how to write unit tests.
Links
-----
- [RT Studio dev tools]
- [`testthat`]
- [R Packages]
---
[RT Studio dev tools]: http://www.rstudio.com/products/rpackages/devtools/
[`testthat`]: https://github.com/hadley/testthat
[R Packages]: http://r-pkgs.had.co.nz/tests.html
Related
Consider this module App::TimeTracker. If you click on the tracker link in the SYNOPSIS section you end up here whereas you should have ended up here. The Pod source code responsible for the behavior is given here, which shows that the following Pod formatting code was used:
L<tracker>
I can fix the problem by providing an absolute link instead:
L<tracker|https://metacpan.org/pod/release/DOMM/App-TimeTracker-3.000/bin/tracker>
but this fixes the link to version 3.000 which may change in the future.
So how should this be done in general?
Use the full path without the version number: https://metacpan.org/pod/distribution/App-TimeTracker/bin/tracker.
The problem is that tracker_bash_autocomplete is not being indexed correctly as documentation by MetaCPAN. The NAME section has a very specific format based on manpages which must be adhered to for MetaCPAN to know how to link to your documentation. Putting tracker bash autocomplete before the hyphen makes MetaCPAN index it as tracker.
=head1 NAME
tracker_bash_autocomplete - whatever
I am working on this project : https://sbl.inria.fr/doc, where the documentation is done with doxygen.
We were used to define the id of our sections with the symbol "-" to separate the words, for example :
\section sec-intro Introduction
However, it looks like the convention has changed since doxygen 1.8.15-git and only alpha-numerical characters are accepted, breaking almost all the pages in our documentation.
Unfortunately, we have a large number of pages, and before reviewing the whole documentation, I wanted to know if there is anything that I am missing, like a doxygen option to turn ON / OFF
[edit]
Here is a minimal example that does not work for me, with doxygen 1.8.15-git:
/**
\mainpage My Main Page
Abstract
\section home-intro Introduction
Intro
*/
//! Documented class test
class test{
};
I just create the configuration file and then run doxygen on the directory containing my .hpp file (so that there is no need to specify the path to my header) :
doxygen -g; doxygen
The main page on the output html contains "Abstract", but not the section, and there is a warning in the doxygen log :
test.hpp:6: warning: Invalid section id `home'; ignoring section
[edit 2]
It worked with doxygen 1.8.14. I cloned the project from the git repository, so I had the latest version. Using the tag version for the 1.8.14, it works fine. I changed the title.
I found the cause of the problem, it is a regression on:
Bug 740046 - Negative sign in -Foo::Bar ruins hyperlink in generated output
The github issue causing the problem is https://github.com/doxygen/doxygen/pull/5677 and the pull request https://github.com/doxygen/doxygen/pull/704.
The issue has been fixed in the proposed patch: https://github.com/doxygen/doxygen/pull/6388
Some of my doxygen documentation need to refer to pages in the
company's wiki. I would prefer if these references resulted in working
hypertext links in the generated documentation. I could of course
achieve this by writing:
/// Name of page
or alternatively using Markdown syntax:
/// [Name of wiki page](http://long-URL.com/wiki/index.php?Name-of-page)
Unfortunately I have to give the full URL at every link in both cases,
and when (as has already happened) the base URL of our company/wiki
changes, all the URLs needs updating.
I therefore wonder if Doxygen has some support to avoid having to
hardcode the entire URL at every link?
For comparison, wikis use "InterMap" or "InterWiki", to define
prefixes that allow a shorthand notation for quickly referring to pages
on another web site. Example:
See WikiPedia:InterWiki_Links for more details.
So if possible I would like to let the Doxygen documentation contain
something like:
// See CompanyWiki:Name_of_wiki_page for bla bla
Some references:
Automatic link generation - http://www.doxygen.nl/manual/autolink.html
InterWiki - https://www.mediawiki.org/wiki/Manual:Interwiki
PmWiki/InterMap - http://www.pmwiki.org/wiki/PmWiki/InterMap
You could define an alias in the config file:
ALIASES += WikiPedia{2}="\2"
and then use it in your comments like so
See \WikiPedia{InterWiki_Links,Interwiki Links} for more details.
See also http://www.doxygen.org/manual/custcmd.html for more info.
How can I view the Markdown of a comment in a GitHub issue? For example, I would like to see the Markdown that makes up this comment:
https://github.com/jashkenas/backbone/issues/3857#issue-116738665
Simply replace username, reponame and issue number in the following url:
https://api.github.com/repos/USERNAME/REPONAME/issues/NUMBER/comments
Here's an example
First, the first post is the actual issue itself, not accessible but the GitHub issue API:
https://api.github.com/repos/jashkenas/backbone/issues/3857/comments
That list only 3 comments, since the first post is not a comment.
The issue itself has a formatted body:
https://api.github.com/repos/jashkenas/backbone/issues/3857
That returns:
"body": "In Safari , pass a path using unicode string to `navigate` method like this\r\n\r\n```js\r\nBackbone.history.navigate('/city/北京',{trigger:true});\r\n```\r\nThe hash is incorrect. It output\r\n\r\n```js\r\nlocation.hash\r\n//> #/city/%17%AC\r\n```\r\n\r\nI tracked the code, it caused by `_updateHash` method.\r\n\r\nThe call stack created by `History.prototype.navigate` method like this\r\n\r\n* navigate\r\n - decodeFragment\r\n - _updateHash\r\n\r\nThe fragment passed to `_updateHash`, was decoded by `decodeFragment`, so the hash was incorrect。\r\n\r\nI also searched the commit history, the `decodeFragment` added in \"1.2.0\"\r\n\r\nPS: My english is not good, although I am trying to improve\r\n\r\n",
That is not exactly mardown:
In Safari , pass a path using unicode string to `navigate` method like this
```js\r\nBackbone.history.navigate('/city/北京',{trigger:true});
```\r\nThe hash is incorrect. It output
```js\r\nlocation.hash
//> #/city/%17%AC
```
I tracked the code, it caused by `_updateHash` method.
The call stack created by `History.prototype.navigate` method like this
* navigate
- decodeFragment
- _updateHash
The fragment passed to `_updateHash`, was decoded by `decodeFragment`, so the hash was incorrect。
I also searched the commit history, the `decodeFragment` added in \"1.2.0\"
PS: My english is not good, although I am trying to improve
The second comment in this issue has two images, so those fancy effects are no markdow:
https://cloud.githubusercontent.com/assets/516562/11164567/62f9ddf6-8b2f-11e5-8aa8-631c1aa84422.gif
[https://jsfiddle.net/leexiaosi/uyp3o6ek/](https://jsfiddle.net/leexiaosi/uyp3o6ek/)
**notice!!!** : please open in safari.
### the record of safari
### the record of chrome
It's probably late. But I could somewhat do it this way (at least in firefox).
I am assuming your intention is to copy the formatting of the comment.
This is not an exact solution, but since GitHub supports HTML tags in comments, this will work just fine.
Right click somewhere at the top of the comment you want to copy.
Inspect element
In the Inspect Element box, you will find a line that's a few lines above the highlighted line which has this code:
<td class="d-block comment-body markdown-body js-comment-body">
Right click on the line having the above code
Select Copy>Inner HTML
Now you can either paste this in a comment box, preview it and you'll be able to see the same formatting, OR use an online HTML to MD converter.
You can see the raw markdown by using "Quote reply" (found after clicking three dots at top right of a comment.
Here's the beginning of the comment you asked for:
In Safari , pass a path using unicode string to navigate method like this
Backbone.history.navigate('/city/北京',{trigger:true});
The hash is incorrect. It output
location.hash
//> #/city/%17%AC
...
Is it possible to include LaTeX-style math in any way with github repo wikis? Googling implies github no longer allows things like MathJax, but most references are years old. What (if any) alternatives are there to including LaTeX-formatted math in github wikis?
You can use chart.apis.google.com to render LaTeX formulas as PNG.
It work nicely with Githhub's markdown:
Example (Markdown):
The ratio of the momentum to the velocity is
the relativistic mass, m.
![f1]
And the relativistic mass and the relativistic
kinetic energy are related by the formula:
![f2]
Einstein wanted to omit the unnatural second term
on the right-hand side, whose only purpose is
to make the energy at rest zero, and to declare
that the particle has a total energy, which obeys:
![f3] which is a sum of the rest energy ![f4]
and the kinetic energy.
[f1]: http://chart.apis.google.com/chart?cht=tx&chl=m=\frac{m_0}{\sqrt{1-{\frac{v^2}{c^2}}}}
[f2]: http://chart.apis.google.com/chart?cht=tx&chl=E_k=mc^2-m_0c^2
[f3]: http://chart.apis.google.com/chart?cht=tx&chl=E=mc^2
[f4]: http://chart.apis.google.com/chart?cht=tx&chl=m_0c^2
https
Some installations of Github Enterprise reject http and work only if you use https
Rendered:
For simple formulas (such as exponents etc) you may one just to use the available render languages. For example, using Textile, you can do:
_E = mc ^2^_
Thiw will be rendered as:
_ is used for italic style and ^ for superscript.
You can do the same thing in Markdown adding some HTML:
*E = mc<sup>2</sup>*
You can see it in action in this very place:
E = mc2
If you're looking for support for complex math formulas, then you have no better option than using a third-party service generating images for you. mathUrl looks interesting.
As input we give it E = mc ^ 2 and it generates the following link:
http://mathurl.com/render.cgi?E%20%3D%20mc%20%5E%202%5Cnocache
There is good solution for your problem - use TeXify github plugin - more details about this plugin and explanation why this is good approach you can find in that answer.
GitLab Wiki and markdown supports formulas. I moved multiple repos for this reason.
Now GitHub officially supports showing Mathjax in the wiki!
In Markdown, just use $ as the deliminator of inline formulas, and $$ as the deliminator of display formulas.
To add math equations to a GitHub wiki, I used mathURL as suggested by Ionică. It will render your LaTeX equations. Append .png to the generated url and use that url as an image (either block or inline) in your markdown.