Bugfix/relative links

[mattpolzin]

Fixes #126

When generating markdown, especially for use in GitHub, I like to rely on relative links as a robust way to link between documentation files living at file paths consistent relative to each other.

When I run the current GitHub Action, the default baseURL is used ("/"). This results in broken links between documentation files within GitHub or the GitHub Wiki.

I think this is partially solved by exposing the --base-url argument via the GitHub action (should this also default to "./" to coincide with the default format of .commonmark?).

That is only half the solution, though, because setting the baseURL to "./" results in Links prefixed with "/./". The solution to the second part of this appears to be straight forward enough, but time, experience, and feedback from maintainers will prove or disprove that!

This PR

1. Exposes the base-url argument via the GitHub action. Defaults the GitHub action's base-url to "./". I think a relative URL works well more often than not for markdown, but I am not at all tied to this default because it also makes sense to use the same default the underlying program uses: "/".
2. Uses URL for path append operation. Ostensibly, this simplifies the code and fixes my problem, but I don't know for sure that this works for all use-cases; I would love feedback on this decision.

I ran documentation generation with a few believable base urls to check some common cases. For a component named "A.B":

1. "" -> [A.B](A_B)
2. "/" -> [A.B](/A_B)
3. "something" -> [A.B](something/A_B)
4. "/something" -> [A.B](/something/A_B)
5. "https://website.com/docs" -> [A.B](https://website.com/docs/A_B)
6. "https://website.com/docs/" -> [A.B](https://website.com/docs/A_B)
7. “./“ -> [A.B](./A_B)

[kongzii]

It would be great to get this merged. Currently, I have to fix links at Home.md after every auto-generation.

EDIT: And links in the Sidebar: https://github.com/SwiftDocOrg/swift-doc/wiki

[mattpolzin]

If anyone wants to temporarily switch to a fork, this fix has been working well for me for a while now. Just update your GitHub job as follows and you can change it back when the problem is fixed in this repo.

  ...
      - name: Generate Documentation
        uses: mattpolzin/swift-doc@bugfix/relative-links
  ...

[mattt]

@mattpolzin Thanks for submitting this, and sorry for not responding sooner. I'm taking a look now.

[mattt]

I just saw your latest changes, and am taking a look at this now. I'll probably write some tests to feel more confident in how this will work.

[mattt]

@mattpolzin @kareman Thank you both for your help in identifying and fixing this bug, and for your patience as I got this merged. I look forward to cutting a new release with this and other improvements this Friday.