Yep, you're right, our Markdown documentation describes a lot of GitLab Flavored Markdown that will (currently) only work inside GitLab itself, not on the docs site which uses a completely different Markdown renderer.

I've added a note to the top of the document encouraging people to view it within GitLab: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5440

You can check out the Videos example in all its glory here: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/mark...

It appears however that it doesn't currently work correctly with files in the same repo, just with absolute links. I've created an issue for that here: https://gitlab.com/gitlab-org/gitlab-ce/issues/20189