convert *to* Creole?

I'd like to move some pages from other wikis to a Creole wiki (bitbucket). However, while I see several ways to convert Creole to *HTML, I don't see any tools that write Creole, i.e., take other formats as input, outputting Creole. Am I missing something?

-- TomRoche 2018-10-18 21:17:32

You can convert to Creole using txt2tags, which has a Creole exporter (btw the txt2tags markup, which is also older, is very close to the creole one). You can also convert most markup to txt2tags, and then to Creole, by using this tool:

-- Farvardin 2013-03-24 08:10:00


I'm noting two problems with the TextCha's:

  1. typo: the prompt How do you call a language that is a mix of other languaues? should instead be What do you call a language that is a mix of other languages?
  2. There's no way (I can see--am I missing something?) to "reload" a TextCha (in the case, e.g., that you don't know the answer) in the way that one can a "normal" captcha image.

-- TomRoche 2012-08-15 23:37:18

Thank you, I fixed the grammar of the question -- I'm not a native speaker, hence the mistake. As for getting a different question -- that is impossible on purpose. If you could easily reload questions, then it would be easy to spam the wiki automatically with a script that only knows an answer to a single question. Right now you can't reload them, so any spamming script will stop after just a few edits and require the spammers to do the work of answering to all the questions.

The questions are designed to be easy to answer by anyone who is familiar with wikis.

-- RadomirDopieralski 2012-08-16 08:04:12

comment syntax

As a

I expect to be able to comment and comment-out. But as a (mostly-happy) new bitbucket-wiki user,

Can this be done in Creole? If so, how? If not, why not? -- TomRoche 2018-10-18 21:17:32

I promised to not participate in WikiCreole discussions after being accused of hijacking it, so I will only tell what I remember from the initial discussions on Creole 1.0 (surprisingly, I can't find those discussions on the original wiki, so take it with a grain of salt) and some of my thoughts following it. The thing about comments is that they are invisible. One of the guidelines we agreed on is that all the markup should be visible on the rendered page, so that there are no surprises or hidden magical incantations. Since this markup is designed for wikis, which in turn encourage all the users to edit pages, there is no need for a mechanism of delivering a separate message to the editor -- one that would be invisible to people who just read a rendered page. Of course, individual wiki engines are always free to implement their own markup for comments -- it's just not included in the common markup defined by Creole. Hope that helps. -- RadomirDopieralski 2012-08-16 10:09:46


Is there somewhere a discussion of html5 changes in creole? e.g.: The <tt> tag is obsolete in html5. It was reccomended to use <tt>, see: (site is down). So use <code> instead of <tt> ? -- JensDiemer 2011-08-08 12:46:09

As I see it, WikiCreole is not an abbreviated form of HTML, or anything like that -- there is no direct correspondence between WikiCreole markup and HTML tags. W3C and others are recommending that you write "semantic" HTML as much as possible -- that is, mark the text up with tags that have meanings, and use CSS and other techniques to give it the right presentation. On a wiki site, you rarely have control over CSS, so unless the site admins provide you with specialized rules and macros for expressing the meanings you need when talking about the wiki site's subject, you have to make do with the basic, presentational markup, possibly explaining it in the text of the page if it has some special meaning. But that means that using the "semantic" HTML tags for that presentation is wrong -- because you are putting meanings on markup that didn't have them -- in particular, when formatting preformatted text with <code> tags, you are assuming that it is always going to be used for computer code. But that is not true, and you can't really tell people to only use it for code. Hence, to be correct in the spirit of HTML, you should be using tags that don't really carry any additional meaning besides the presentation.

Now, there is a number of choices available:

I'm going to contact the guys who host the spec and let them know about it being down. -- RadomirDopieralski 2011-08-08 19:37:17

URL Discussion

Moved to Creole 1.0/additions/Discussion. It's easier to not repeat ourselves all over.

The the old wiki has a quite nice graphic that shows that many wiki engines choose to use the much more user friendly way of putting the explanation first in a link. This is different from html - but it should not be the goal of the wiki engine to read like html. Especially if many links are long and used in text or in a list it is really hard to find where the description is (it is usually pretty short compared to the link). Also this mirrors the very old and often used free form that people use when just writing ascii text about something: First the explanation and then the link. Often in the form of (Find more info here: <url>)

Therefore I propose that for Creole 2.0 explanation before links should be made standard. --Martin Häcker

I agree with Martin Häcker, and for a reason not yet cited here (although I did put it forth somewhere a long time ago)--I often want to sort a (for example, bulleted) list of links--the sort is always (for me) based on the text (explanation), not the URL (link). If it is arranged as Martin proposes, it is very easy to sort in almost any editor. --Randy Kramer, 20110105

We had a long and winding discussion about this on the old wiki, and we failed to provide any hard facts and evidence in favor of either approach. While the order you suggest might be favored when you link to urls, it might not work as well when linking to other pages on the same wiki (and a wiki usually mostly has internal links). In the end it turns out to be a matter of preference and habituation. I really don't see any compelling reasons to change the initial decision (even if it wasn't based on hard evidence) and break compatibility not only with half of the wiki engines that made similar decision, but also with earlier versions of Creole itself. Remember, that the main goal of creating this project in the first place was to find a cure to the interoperability nightmares caused by proliferation of different wiki markups. Introducing more variety in behavior would be counter-productive. -- RadomirDopieralski 2009-03-13 17:38:24

See also:

I agree with Radomir: This would (unnecessarily) break compatibility with earlier versions of Creole for questionable reasons. Even if there were good reasons everyone agrees to for doing it this way it wouldn't be worth breaking backward compatibility.

I thing these are laudible goals for Creole, but I also think that it is missing the main point. Still most users of wiki-markup come from never having used a wiki before - and they are the ones who are most surprised by this behaviour, as the standard before wiki was text first, url second. If it boils down to either way should be fine, then I'd strongly suggest going with what most new users surprises the least. -- Martin Häcker

On an alternative thought: Wiki Syntax probably isn't as important for new users anyway, as they will always prefer using a GUI Editor (and continue to do so), as it provides way less surprises and new things to learn for them - and Most Important wikis now offer these. That thought does make it easier for me to live with a (to me) less than ideal syntax. --Martin Häcker

I agree with what Martin Häcker and JanneJalkanen said about linking order. It's not because most wiki has choosen link first, description after, that it's the most rationale idea. I think a wiki syntax has reach its goal when you can fluently read without being parsed.

It's what we call [[ | usability]]. Some people may find [[usability |]] is not at its best when the link is written first. What do you think? ;)

Sorry for the flashing blue, I was only intending to show that it's easier to read with the description first instead of with the link first.

There will be differences for sure between the 1.0 and 2.0 format, so the fact it might break the 1.0 may prevent the 2.0 to find a better and more rationale syntax. Is there a special tag in the header of the text for saying which creole version it will be? --Farvardin

I've been through the discussion about URLs in link on Creole 1.0 discussion page, and came with this simple thought. Seems to me that it is really important that a wiki created with Creole 1.0 continue working without too much modifications when upgrading to Creole 2.0. So I think it is important that the link logic that first prevailed remains. It's actually the idea behind a wiki to create new links with actual text by just putting the braces around it. In that case, it seems more intuitive to put link first, alternate description after, since the latter is optional.

But I definitely agree that links using URLs look and read better when the description comes first. And it's actually quite possible to allow this without breaking compatibility with the earlier version of Creole : When parsing a link, it's easy to determine which part is an URL, and which parts are text. If the link has only one part, that part serves as both link and description. If one part is an URL, then Bingo!, the URL part is the link, the other one is the description, no matter the order. And when both parts are text, let's do as usual and use the first one for the link, the second for description. This keeps compatibility, and allows people to use the alternative they prefer for URLs (the only case for which it actually matters), without rendering URL links from Creole 1.0 invalid. -- BigueNique 2012-07-09 00:29:13

Just out of curiosity, what happens when both parts are URLs?

Making Creole 1.0 additions mandatory

I think one of the first things one should ask is whether there are Creole 1.0 additions that should be made mandatory in the next version. I think ^^superscripted^^ and __underlined__ might be candidates. What do you think?

Since nobody replied, I'll give it another try: Creole 2.0/1.0 additions in 2.0. -- MarioLenz

Markdown uses double underscores for alternative bold. -- JAbits

Simplicity vs. power

There have been some proposals on Creole 1.0/additions/Discussion about CSS or something similar... I strongly advise not to bloat the standard. Feature creep is probably the biggest problem in IT, both in software and in standards. Adding more and more features to please everyone inevitably leads to frustration. WikiCreole should stay lean and mean in order to make it easy to implement and use. "Keep it small and simple" is a very wise design goal on the long run. For example: CSS might be replaced by something else one day, but it is quite likely that people will always use bold and italics, headings, tables and lists.

comment of FBnil: In WikiOnAStick we use css to complement the markup. For example, a strike-through produces a strike tag with class="woas_strike". This class can then be updated by the user to make it red, or cross it out with XXXX instead of a line. So there is a strong interaccion with CSS. Now, the only way your page is going to look as you want it is to use HTML with inline styles, true, but we can wrap that into a macro, and then it looks like an extension... in conclusion: keep the core small, the rest is possible using <<macro's/extensions>>

More powerful image tags

{{?image?wxh:v-align?|alternative text|stylesORclass}}

Here we can add a space on one or either side of the imagename to center it, or float it left/right The questionmark ends the imagename and starts the optional markup, width and height, and a way to set vertical alignment (very useful for small inline images). Example: {{|a gnu image}} The third option is what we use in our wiki, but it might be bloat for Creole 2.0. It gives the image a class, or if a colon is detected, it adds it as style.

exclamation is a one-liner note

I know this conflicts with headers (for which we use = but many Wiki's use !), but I'd like to propose:

! {{images/info.png}} This is a colored information div with an inline image and important information

This is an extension to this syntax (but might be feature bloat):

!{bluebox oval} This is a div with class="bluebox oval" and presents the information in a different way



The documentation of which markup element can contain which other kinds of elements is a bit unclear in Creole 1.0. It would be helpful to state clear which element types can be contained.


Can contain: Break, Image, Link, Strong Text ...
Can be contained in: none

Strong Text
Can contain: Emphasized Text, Link
Can be contained in: Paragraph, List Item, ...

According to WikiMatrix, only PmWiki supports this (see WikiMatrix' external and internal link markup). Since WikiCreole is also about interoperability, I would remove this addition in Creole 2.0. It's like this: Whoever uses this syntax- be it a wiki engine developer or a user- is not concerned about interoperability, otherwise they would use the WikiCreole standard that is guaranteed to work in all WikiCreole wikis. If you're concerned about interoperability, stick to the core standard. If not, why stick to the additions instead of doing it in a completly different way?

Besides, as someone stated on Creole 1.0/additions/Discussion: "There should be one, and preferably only one, obvious way to do it."

Italics in headings

This observer would like to comment that it seems odd that italics can't be used in headings. I can't find an explanation for this decision and this would be a good fix for 2.0. It's quite reasonable to want to use italics for emphasis or foreign terms used in headings. Ironically, the immediate previous section heading in this page could benefit from this change.

List items with newlines and paragraphs

What do others think of this markup proposal?

Example list caption:
  * Item A (conventional)
  * Item B (continued), ending with newline.
    : Item B continuation in the same paragraph.
    : Item B continuation in another paragraph.
  * Item C (conventional)
  Preformatted text, such as this, without any prefix terminates the list.
Regular text, such as this, without any prefix also terminates the list.

comment of FBnil: Looks logical, and looks like indentation (but because there is a space before the :, it should not conflict. In WoaS we use a trailing backslash to continue a line (it eats up the newline) and double backslash to eat the newline and replace it with <br> (force a linebreak). Another option is to have them at the same level of the asterisk, while less easy on the eyes, looks easier to parse and makes it similar to ;definitionlist :definitiondetails.

Hierarchical Document Trees and Navigation

I would like to see a conversation around standardizing a way to establish parent-child relationships between pages (or between multiple sections within a single body of wiki markup) for the purposes of hierarchical document representation and navigation.

Before the internet most information was in books. Many books were organized into chapters and sub-sections that directed the reader through a logical progression of the material. Flip to the table of contents in the front and what you will usually find is a hierarchical tree-like organization of information. Flip to the index at the back and what you have is essentially a keyword search engine.

Today most wikis have the keyword search engine (the book index), but many are weak when it comes to defining a document hierarchy (the table of contents). Now not every wiki has content that lends itself well to a document hierarchy, but it is a common enough use case that many "Table of Contents" implementations and "Tree Navigation" extensions have sprung up for the various wiki engines. The syntax for these varies widely today. A standardized way to represent a document hierarchy would be a good thing for wiki markup.

Furthermore, many book oriented document systems have been developed that embrace this type of tree organization, running the gambit from TexInfo to DocBook. But many find such systems awkward or impractical to use. Recently some book style document generators have been embracing wiki markup as a way to represent content. Document generators such as txt2tags and AsciiDoc are examples of this. Even DokuWiki is partially into this space. Systems such as these could also greatly benefit from a defined standard for hierarchy representation in the wiki markup.

It would not take much to enable this. Much of the functionality can already be done explicitly today with just urls, but a few tweaks could help. One idea is extending the url syntax as follows:

[[link_address|>|link text]] : Defines a link to the Next page
[[link_address|<|link text]] : Defines a link to the Previous page
[[link_address|^|link text]] : Defines a link to go Up one level to the Parent

With simple additions like these a wiki engine could deduce and display navigation for hierarchical documents on it's own. Also document generators (and wiki engines for that matter) could automatically build tables of contents from these links by combining data from multiple pages.

As an aside, for document generators it's common to have multiple sections/nodes/pages in a single body of markup. For those cases it would be useful to have an indicator that marks the beginning of a new section/node/page within the markup. That indicator would contain the link address to be generated, or in the case of a wiki engine, a url or anchor that can be referenced from elsewhere in the wiki:

[[link_address||link text]] : Defines the beginning of a new node within a single body of markup containing multiple nodes.
(Or maybe this can just be some variation of anchor syntax?)

Granted those forms of syntax are just quick ideas without much thought behind them. My real point is to start up a discussion in the community of how document hierarchy might be standardized, paving the way for new features such as navigation and automatic contents generation in wiki engines, as well as helping Creole make inroads to wiki markup based document generation systems.

FBnil Comment: Like this idea very much, but just not the syntax. (still pondering its usefullness)



I do not think I follow you when talking about multiple sections, in that case you need to use anchors to scroll through the page [[thispage#anchor|>|next]]. Does creole have anchor syntax? Where can I find the syntax? is it like =#anchor Title in H1 I'd rather have an extra optional class in the link tags: [[link_address|title|link text|class]], from there use CSS to align it to the right/left and give it some nice look and feel. (instead of rendering link ">" differently) Now imagine indexing a full wiki, with pages that have multiple sections... that's hard. But let me think about this (for a "choose your own adventure" wiki, how it all would look like). An equivalent idea using the macro syntax (not in the Creole2 core):<<<navbar("back", "top", "bottom")>>>

Aims and Compatibility

Hi, I've added an aims and suggested compatibility onto the front page. I've done this not only because I think it is necessary if creole is going to go anywhere that it understands what it is trying to achieve but also because I think it will provoke people to think through some of the issues (like e.g. subscript). The big problems Creole has had is that the application developers are reluctant to include things in the standard which they personally don't see a need for. This is entirely the wrong way around, because far from only agreeing the "worst common denominator spec", what users are crying out for is the other way around: "common markup for common formatting, and the surety of knowing that you won't get caught by some application specific oddity in the way they implement their markup". So, it isn't enough to agree on how to do a link, but then find that single square brackets have some meaning in a particular wiki, so that you have to spend hours trhying to understand how that particular wiki might just allow you to enter single square brackets. And what does it matter if Creole specifies a way to do things which many wikis might not wish to do??? COME ON!!! Let's be honest, if you don't want to have references, footnotes, colours or whatever, why don't you just let those who do want those additional features work out a way to do them and allow those who don't to derogate from the specification. So long as the user is told explicitly that the wiki doesn't do some features, then there are good reasons not to implement every feature on every wiki, but there are no good reasons to stop people who do aspire to have such features coming to a common agreement.

<What's the point of a specification that doesn't even let me know how this wiki lets me sign my comments about that specification>

If you read the goal statement of WikiCreole you will surely discover, that it was never to force the presence or absence of a certain set of features onto wiki engines. On the contrary, an effort has been made to only define the most essential markup that can be found in most wiki engines, and to leave the standard open-ended. This wiki is open for general public (in fact, I don't think there are any people left who would be willing to take responsibility for WikiCreole), so it may seem like it's simply a wish-list, a place where people can demand features they miss, because when they become standard everybody will be forced to implement them. Personally I don't think it works that way. Even demanding documentation in the standard -- although surely done with a noble goal -- isn't likely to have much effect. Developers won't listen to you if all you do is making demands. What they (we) want is ready solutions for the design problems -- solutions that are maybe not perfect, but at least good enough and agreed upon. And of course, if it comes with free documentation and tutorials that you can reuse -- it's even better.

I don't mean to discourage you from working on WikiCreole -- I can see you are already putting a lot of energy into it. I just don't think there is anybody here to try to convince to your points.

Oh, and by the way, you sign your comments the same way you do it in the real (non-Internet) world, and in many places on the Internet too -- with your name. You might be able to find some of the documentation that you crave by typing 'help' in the search box too. I hope that helps. -- Radomir Dopieralski

CreoleWiki: Creole 2.0/Discussion (last edited 2013-03-24 07:13:58 by lns-bzn-33-82-252-62-185)