Curly links prepend trailing / from URL to the front of <a> text

[DanRathbun]

Curly links prepend trailing / from URL to the front of text.

SOLVED

Loren has tracked this down to the default Rdoc markup helper.
Red Carpet does not have this problem.

Where are curly links processed ?

A: Doesn't matter, install a better markdown parser gem and YARD will use it.

Steps to reproduce

Snippet from a project "Release Notes.md" markdown file in a "pages" subfolder:

## Developer Center

Between the new Extension Digital Signature Page, the new LayOut C API and a whole lot of future ideas and
potential, we have decided to create a new central location to organize our developer resources, API documentation,
 etc. Visit (and bookmark!):

* {https://developer.sketchup.com/ SketchUp Developer Center}

Actual Output

Developer Center

Between the new Extension Digital Signature Page, the new LayOut C API and a whole lot of future ideas and potential, we have decided to create a new central location to organize our developer resources, API documentation, etc. Visit (and bookmark!):

• / SketchUp Developer Center

~

[lsegal]

I'm unable to reproduce an issue here:

Which Markdown library is being used to generate that output? I have tested with redcarpet, rdiscount, kramdown, and maruku, and get the same result as above for all of them (yard -m markdown -M kramdown).

Generally speaking, {} text is processed after markdown, so without seeing the fully generated raw HTML it's hard to understand what would be going wrong here. The / prefix makes me wonder if your specific Markdown formatter is processing the curly braces itself, which may be some custom extension to the Markdown format and likely not well supported by YARD.

[DanRathbun]

Which Markdown library is being used to generate that output?

I am using ThomThom's official template for SketchUp API YARD docs. I think he has changed things and is using Rouge ?

The latest is here ...

https://github.com/SketchUp/sketchup-yard-template

But I am using what he posted to RubyGems which is v 1.4.0 ...

https://rubygems.org/gems/yard-sketchup

Where will I find the markdown parser setting ?

EDIT: My specific yardopts file does not have a -m argument, ...
So Either the yard-sketchup gem template is setting the parser, or I'm using the default.

[DanRathbun]

Oh and I see this with YARD 0.9.26

[lsegal]

So Either the yard-sketchup gem template is setting the parser, or I'm using the default.

The default will depend on what your system has installed. YARD selects from the list in YARD::Templates::Helpers::MarkupHelper

FWIW if you're using Markdown explicitly, the recommendation would be to use Markdown formatted links directly for URLs, not YARD's {} link syntax:

* [SketchUp Developer Center](https://developer.sketchup.com/)

[DanRathbun]

Generally speaking, {} text is processed after markdown, so without seeing the fully generated raw HTML it's hard to understand what would be going wrong here.

The file is HUGE ... but this is the generated output ...

<ul>
  <li>
    <p>
      <a href="https://developer.sketchup.com" target="_parent" title="/ SketchUp Developer Center">/ SketchUp Developer Center</a>
    </p>
  </li>
</ul>

The / prefix makes me wonder if your specific Markdown formatter is processing the curly braces itself, which may be some custom extension to the Markdown format and likely not well supported by YARD.

This is not the only weirdness.

I've noticed that if there are "normal" [Link Text](https://some/path/to/filename.html) kind of links in the same heading block (created with ## markdown) that subsequent curly links to local project classes are not generated. They just come out as {ClassName} plain text.

These "normal style" links themselves were actual links into the local YARD generated docs, but had hardcoded URLs to the generated Git Page pages. (These links came from someone pasting in chunks of notes into the YARD pages document.)

This was easily solved by converting these "hardcoded" markdown links to YARD curly links that YARD then built and linked correctly when generating the "pages" files. Once these links were correctly generated, the following YARD curly links in that heading block were also generated and linked correctly by YARD.

[lsegal]

Note: I've reproduced this with the rdoc markup formatter, which is likely what you have installed if you have not added any markdown processing libraries on top of the default set of Ruby 2.x gems.

This, however, seems to be an issue with RDoc's markdown processor and is not related to YARD, since RDoc seems to be autolinking the URLs prior to YARD processing the brace syntax. In other words, the input YARD is getting after the markdown pass is:

<p>{<a href="https://developer.sketchup.com">developer.sketchup.com</a>/ SketchUp Developer Center}</p>

It seems as though rdoc's markdown processor is separating the trailing / from the link in its own output. If you must rely on rdoc's markdown processor, the workaround would be to avoid trailing slashes on URLs, or use Markdown's standard linking syntax instead of YARD's here.

[DanRathbun]

If you must rely on rdoc's markdown processor, the workaround would be to avoid trailing slashes on URLs

I don't! and of course I removed the trailing slash in this instance. But I am not the original author to much of this 20 years worth of documentation. So there is likely other instances where trailing slashes might "rear their ugly head". Some technical authors love to always put a trailing slash on URLs. I wonder if this is an Apple thing? (Mac users tend to do this.)

I've reproduced this with the rdoc markup formatter, which is likely what you have installed if you have not added any markdown processing libraries on top of the default set of Ruby 2.x gems.

Good detective work!

I followed instructions (which are apparently incomplete) as those instructions said I only needed the yard gem and the yard-sketchup gem to process the API stubs into documentation.

The default will depend on what your system has installed. YARD selects from the list in YARD::Templates::Helpers::MarkupHelper

I would definitely like to get away from this problematic Rdoc parser as the stubs are pure Ruby and there is no Rdoc markup/down in any of the code snippets in any of the files.

So, I just popped into IRB and installed the Red Carpet gem. Let's see what happens ...

Yes. okay. The trailing slash is gone. And ... it seems like yardoc built the docs must faster !

I'll do some more tests and see if using this "helper" solves other quirky things with embedding HTML fragments I noticed with the Rdoc parser.

MANY THANKS Loren !

[DanRathbun]

Another weird thing I noticed with the Rdoc parser was that in order to inject special CSS styles for only one files page out of the 13 I have so far, I had to put the <link> element within <p> block, viz:

<p>
<link rel="stylesheet" href="css/build_table_styles.css">
</p>

The generated HTML output still wraps the <link> element in a paragraph as above, but RedCarpet does not make me do it in the markdown document.

---

So those new to YARD may not understand that they need to also install a better markdown parser gem.
I thought that they were probably included with YARD or custom templates.

It is amazing at what a simple gem install "redcarpet" command can do !

I had read the following and did not get this information from these parts:

• https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#which-markup-format

• https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#documenting-extra-files

~

[DanRathbun]

Shall we close this or would you like to use it as a reference for a documentation issue ? (See the above post.)