need internal link text #140

kbigler opened this Issue Feb 27, 2012 · 11 comments


None yet

4 participants


To avoid awkward sentence construction around internal links to previously-created pages, I'd like to be able to specify the visible link text for an internal link.

I dont' know if it might apply but I can't find an explanation for the use of a "link slug" mentioned in Concepts.

[I don't know my way around here--don't know if I should have made a post somewhere to introduce myself.
I'm a little weak on a lot of the specific technology you use but have 30 yrs of C/C++. I have considerable interest in this project, and for now limited time. I'm in Berkeley, CA.]


Welcome! An issue is a perfectly good place to introduce yourself.

I just gave a concept of this a shot on a branch here. The syntax I'm trying is [[Title of Page] optional shown text]. Seems to workout as I'm trying it out. Let me know what people think.


I have to admire Nick's suggestion since it is more self consistent than the internal and external link markup offered by MediaWiki. MediaWiki uses a vertical bar in one and not the other. I admire it but don't want to do it. Let me explain.

I suggest we move away from markup as much as possible in the default paragraph type. I've been mixing in a bit of html syntax but I'd like to put a stop to that. To that end I'd like to add a new story element type: html.

The html plugin would enforce a subset of html that is compatible with the federated wiki software. That means italic, bold, headings for sure. I'd also like to see a variation of the current TextEdit that understands html and makes sure novices get it right. With the html paragraph type we can then limit the default to not use html tags at all. Angle brackets would be angle brackets again.


The link slugs are down-cased and url friendly names of pages. This means you do have case freedom in your references if not tense or plurality.

The slug algorithm is not quite what I intended but as we gather more content it becomes harder to change. We should add finalizing this algorithm to our list of things to do before we start numbering releases. (We're not yet to version 0.1) Of special concern here is reasonable behavior with international names.


I agree that we don't want to be inventing our own markup language, there are plenty out there already, and they can be dealt with well in the plugin space. However reading this I'm not clear on what we want the default paragraph type to end up, html backed wysiwyg?


I have yet to learn about your underlying models and representations, so let me ask a naive question.

If you have a paragraph-type concept maybe you could have paragraph types like "prototype-1" and have in the environment a specified current-default paragraph type which might for now be "prototype-1" (not "default"). Then perhaps without too much effort you can as needed change the current-default paragraph type and simultaneously deprecate some paragraph types but retain them to keep existing content working. Then when a paragraph of a deprecate type is edited, warn the editor but make it their responsibility to correct as needed to conform to the syntax requirements for the new type. This would keep things moving forward while permitting different markup practices to co-exist in the environment and not get in each others way.

Of course I understand that might violate keep-it-simple but have no sense of the weight of the issues involved.


The link slugs are down-cased and url friendly names of pages

Ah, ok, so I take it link-slug just refers to what is generated by the [[...]] syntax which also determines the file name created for the page. So not something used directly (when editing), except as needed for any links from outside.

MediaWiki uses a vertical bar in one and not the other

I had googled up MediaWiki but could not grasp the syntax charts, also had no idea which subset you had implemented so seemed not worth pursuing. Is there currently a way without Nick's branch to give different shown text to an internal link, perhaps using the vertical bar you mention?


Yes, you can currently write whatever html you want in a paragraph so if you want tags to work like they do in html, you have html. I consider this a dangerous practice but would like to offer an item type == "html" where it is allowed.

Federated wiki has an enhanced linking mechanism which is different than that offered by the html anchor tag. I would like to reserve the [[ ]] syntax for those federated links. This is really what the project is about.

I should probably write something about this. For now I have a new video which hasn't yet found its way to the video collection:

I would like the default paragraph type to be plain text, flowed into the available space, suitable for a single paragraph, augmented with [[ ]] and [ ] links. This says, at the paragraph level, words and links are the only things that matter.

I'm against alternate text for links for a variety of reasons enumerated in an essay here. If one really wants to use alternate form in plain text links then the [ ] link syntax is available, only without the special federated wiki link semantics.

@kbigler suggests a good method for migrating from our current situation to new paragraph types, say plain and html, which are not quite the mime interpretation of these words, but close.

nrn commented Mar 1, 2012

Ok, so that's a fairly compelling essay.


Wagn uses [[<link>|<link text]] and <link> can be either an internal link (card name) or URI. Early Wagn had [URI][<link text>] maybe just for external, but I think a unified form works best. I think this is borrowed from somewhere else. Let's try to use something that's already invented :)


I'm against alternate text for links for a variety of reasons enumerated in an essay here [] [].

The problem is somewhat mitigated by the fact that the link id (url or internal) does not have to be completely hidden, e.g., it might be made readily visible via a float-over, although I'm really not in love with float-overs in their familiar and often dysfunctional form.

Secondly, regarding the title of the article, the problem is worse for external links for which the title is not available at all unless the site is live, whereas with SFW internal links the link identifier is the title.

So it would appear to be more of a problem to allow alternate text for external links than for internal links, if some natural process or hint would lead the viewer fairly directly to the link superceded by the alternate text.

As things stand you can give alternate text for an external URL and it is still not clear to me whether in the current implementation you can for an internal link.

There is always that question about whether tools that risk shoot-in-the-foot behavior should be withheld. My usual response is to allow it with the combination of making the usage not entirely obvious and providing appropriate warnings. The idea would be that people who can discover the method will have the opportunity to see the warnings.


I've written user documentation for federated wiki link syntax and semantics on the How To Wiki pages.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment