You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mesos.apache.org by Jörg Schad <jo...@mesosphere.io> on 2016/01/14 13:44:17 UTC
Links in documentation
Hi,
just a short note about links in our documentation.
In the current documentation we use three different ways to link between
different *.md pages:
1. [label](/documentation/latest/foo/)
2. [label](foo.md)
3. [label](https://github.com/apache/mesos/blob/master/docs/foo.md)
First of all, option 3 should *not* be used as it is rendered incorrectly
onto website* and rather long.
Between option 1 and 2 Neil and myself discussed (MESOS-4295) and are
favoring option 2 as it
- previews better on github
- is shorter
- is easier to maintain multiple versions of the same doc.
Any comments or objections?
Thanks for your feedback!
*In fact it seems that all links ending with .md are interpreted as
relative links on the webpage, i.e. [label](https://test.com/foo.md) is
rendered into <a href="/documentation/latest/https://test.com/foo/
">label</a>.
Re: Links in documentation
Posted by Kevin Klues <kl...@gmail.com>.
So by 2 you mean relative links to the *.md files vs 3 which is
absolute (from the repos topdir).
If so, +1
On Thu, Jan 14, 2016 at 11:39 AM, Joris Van Remoortere
<jo...@mesosphere.io> wrote:
>>
>> *In fact it seems that all links ending with .md are interpreted as
>> relative links on the webpage, i.e. [label](https://test.com/foo.md) is
>> rendered into <a href="/documentation/latest/https://test.com/foo/
>> ">label</a>.
>
>
> I think this should be fixed. We shouldn't be restricted from linking to
> external documentation.
>
> —
> *Joris Van Remoortere*
> Mesosphere
>
> On Thu, Jan 14, 2016 at 4:44 AM, Jörg Schad <jo...@mesosphere.io> wrote:
>
>> Hi,
>> just a short note about links in our documentation.
>> In the current documentation we use three different ways to link between
>> different *.md pages:
>> 1. [label](/documentation/latest/foo/)
>> 2. [label](foo.md)
>> 3. [label](https://github.com/apache/mesos/blob/master/docs/foo.md)
>>
>> First of all, option 3 should *not* be used as it is rendered incorrectly
>> onto website* and rather long.
>>
>> Between option 1 and 2 Neil and myself discussed (MESOS-4295) and are
>> favoring option 2 as it
>> - previews better on github
>> - is shorter
>> - is easier to maintain multiple versions of the same doc.
>>
>> Any comments or objections?
>>
>> Thanks for your feedback!
>>
>> *In fact it seems that all links ending with .md are interpreted as
>> relative links on the webpage, i.e. [label](https://test.com/foo.md) is
>> rendered into <a href="/documentation/latest/https://test.com/foo/
>> ">label</a>.
>>
--
~Kevin
Re: Links in documentation
Posted by Jörg Schad <jo...@mesosphere.io>.
FYI: We fixed
- the linking to external .md files (MESOS-4384),
- an issue of linking to anchors,
- and also unified links to md pages inside our documentation as proposed
above (MESOS-4295).
On Thu, Jan 14, 2016 at 10:15 PM, Neil Conway <ne...@gmail.com> wrote:
> On Thu, Jan 14, 2016 at 11:39 AM, Joris Van Remoortere
> <jo...@mesosphere.io> wrote:
> >> *In fact it seems that all links ending with .md are interpreted as
> >> relative links on the webpage, i.e. [label](https://test.com/foo.md) is
> >> rendered into <a href="/documentation/latest/https://test.com/foo/
> >> ">label</a>.
> >
> > I think this should be fixed. We shouldn't be restricted from linking to
> > external documentation.
>
> I opened https://issues.apache.org/jira/browse/MESOS-4384 for this.
>
> Neil
>
Re: Links in documentation
Posted by Neil Conway <ne...@gmail.com>.
On Thu, Jan 14, 2016 at 11:39 AM, Joris Van Remoortere
<jo...@mesosphere.io> wrote:
>> *In fact it seems that all links ending with .md are interpreted as
>> relative links on the webpage, i.e. [label](https://test.com/foo.md) is
>> rendered into <a href="/documentation/latest/https://test.com/foo/
>> ">label</a>.
>
> I think this should be fixed. We shouldn't be restricted from linking to
> external documentation.
I opened https://issues.apache.org/jira/browse/MESOS-4384 for this.
Neil
Re: Links in documentation
Posted by Joris Van Remoortere <jo...@mesosphere.io>.
>
> *In fact it seems that all links ending with .md are interpreted as
> relative links on the webpage, i.e. [label](https://test.com/foo.md) is
> rendered into <a href="/documentation/latest/https://test.com/foo/
> ">label</a>.
I think this should be fixed. We shouldn't be restricted from linking to
external documentation.
—
*Joris Van Remoortere*
Mesosphere
On Thu, Jan 14, 2016 at 4:44 AM, Jörg Schad <jo...@mesosphere.io> wrote:
> Hi,
> just a short note about links in our documentation.
> In the current documentation we use three different ways to link between
> different *.md pages:
> 1. [label](/documentation/latest/foo/)
> 2. [label](foo.md)
> 3. [label](https://github.com/apache/mesos/blob/master/docs/foo.md)
>
> First of all, option 3 should *not* be used as it is rendered incorrectly
> onto website* and rather long.
>
> Between option 1 and 2 Neil and myself discussed (MESOS-4295) and are
> favoring option 2 as it
> - previews better on github
> - is shorter
> - is easier to maintain multiple versions of the same doc.
>
> Any comments or objections?
>
> Thanks for your feedback!
>
> *In fact it seems that all links ending with .md are interpreted as
> relative links on the webpage, i.e. [label](https://test.com/foo.md) is
> rendered into <a href="/documentation/latest/https://test.com/foo/
> ">label</a>.
>