Wikitext docs overhaul first step #6828
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,15 +1,23 @@ | ||
| created: 20131205155227468 | ||
| list: [[Headings in WikiText]] [[Paragraphs in WikiText]] [[Hard Linebreaks in WikiText]] [[Formatting in WikiText]] [[Dashes in WikiText]] [[Block Quotes in WikiText]] [[Lists in WikiText]] [[Definitions in WikiText]] [[Tables in WikiText]] [[Code Blocks in WikiText]] [[Typed Blocks in WikiText]] [[Images in WikiText]] [[Horizontal Rules in WikiText]] [[Linking in WikiText]] [[Variables in WikiText]] [[Macro Definitions in WikiText]] [[Macro Calls in WikiText]] [[Macros in WikiText]] [[Transclusion in WikiText]] [[Transclusion and Substitution]] [[Styles and Classes in WikiText]] [[HTML in WikiText]] [[Widgets in WikiText]] [[WikiText Parser Modes]] | ||
| modified: 20220726132727329 | ||
| tags: Concepts Reference | ||
| title: WikiText | ||
| type: text/vnd.tiddlywiki | ||
|
|
||
| \define openAll() | ||
|
There was a problem hiding this comment. If this is a useful feature then it should be made universally available, and not just buried in one particular docs tiddler. One of our key goals with the documentation is consistency. The value of consistency across the docs more than outweighs the advantages of a random, isolated improvement like this. |
||
| <$set name=wList filter="[[WikiText]] [enlist{WikiText!!list}]"> | ||
| <$action-setfield $tiddler="$:/StoryList" list=<<wList>>/> | ||
| \end | ||
|
|
||
| ~WikiText is a concise, expressive way of typing a wide range of text formatting, hypertext and interactive features. It allows you to focus on writing without a complex user interface getting in the way. It is designed to be familiar for users of [[MarkDown|http://daringfireball.net/projects/markdown/]], but with more of a focus on linking and the interactive features. | ||
|
|
||
| ~WikiText can also be inserted to the text field using the [[Editor toolbar]]. | ||
|
|
||
| The following elements of WikiText syntax are built into the core. | ||
|
There was a problem hiding this comment. Do we use the phrase "elements of wikitext syntax" elsewhere in the docs? Again, we should try to be consistent with terminology. We could say the "The following WikiText syntax rules are built into the core", but perhaps there is another collective noun/phraser that we already use. |
||
|
|
||
| <$button actions=<<openAll>> >Open all tiddlers from the list below</$button> | ||
|
|
||
| <<list-links "[tag[WikiText]]">> | ||
|
|
||
| Also see [[Formatting text in TiddlyWiki]] for an introduction to WikiText. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| code-body: yes | ||
| created: 20220726132935807 | ||
| list-after: $:/core/ui/ViewTemplate/body | ||
| modified: 20220726134215137 | ||
| tags: $:/tags/ViewTemplate | ||
| title: $:/editions/tw5.com/wikitext-template | ||
|
|
||
| <$list filter="[all[current]tag[WikiText]]" variable="listItem"> | ||
|
There was a problem hiding this comment. Again this feels like a local, isolated fix to a universal issue. All we're doing here is providing a link back to one of the tags on the current tiddler. That's already possible using the tag pill. Randomly providing another means to do the same thing just makes it look like we don't trust the tagging mechanism as a means of user navigation. There was a problem hiding this comment. From the feedback we get from new users. It isn't enough, to have "hidden information" behind the tag-pill. Because new users don't know about it. If I search for "Formatting" in the sidebar search I may find: "Formatting in Wikitext" and open it. ... My expectation is, that I do get all the info. ... But the tiddler only contains one part of the info. ... That's why I think it makes sense to tell the users, that there is more. There was a problem hiding this comment. That's all reasonable logic, but if it is true then it would actually be an argument for adding breadcrumbs to each docs tiddler, not for making a random isolated improvement for a single tag. There was a problem hiding this comment. OK. What about a "tip" eg: There was a problem hiding this comment. eg: IMO It's a call to action to "use the tagging system" and if they click the link the effect is similar
|
||
|
|
||
| --- | ||
|
|
||
| [[All options to format wikitext can be found at WikiText|WikiText]] | ||
| </$list> | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,19 +1,34 @@ | ||
| caption: Formatting | ||
| created: 20131205155959399 | ||
| modified: 20220726132504220 | ||
| tags: WikiText | ||
| title: Formatting in WikiText | ||
| type: text/vnd.tiddlywiki | ||
|
|
||
| <style> | ||
| .no-code-border > code { | ||
| border: initial; | ||
| background-color: initial; | ||
| } | ||
| </style> | ||
|
There was a problem hiding this comment. (a) the core never uses local style blocks, nor do we recommend their use (b) why aren't these styles in one of the docs stylesheets? There was a problem hiding this comment. b) Because I forgot to move them sorry. |
||
| Available character formatting includes: | ||
|
|
||
| <div class="no-code-border"> | ||
|
|
||
| |Wikitext | Editor Button |HTML |Rendered Output |h | ||
|
There was a problem hiding this comment. Second col has centered headline text. Maybe change third col heading "HTML" into "HTML equivalent" or "rendered HTML" or some such because the people reading this whole tid are typically beginners and may otherwise believe that they need to know this (i.e learn html) Overall for the table, I imagine an English teacher complaining about using "2" instead of "Two" or "Double". There was a problem hiding this comment.
That's intentional. The buttons are centred too. It looks better.
I think I'll remove that column and add the HTML output to the end of the tiddler. eg: For those who are interested.
That's intentional 2 ... IMO the number is much more visible as the word two. It's especially needed for |
||
| |```backticks` ``are used for for code | (<<.icon $:/core/images/mono-line>>) |`<code>backticks</code>` are used for code|`backticks` are used for for code | | ||
|
There was a problem hiding this comment. IMO the output looks better with... hm I need to type it explicitly because github renders it otherwise: backtickbacktick space backtickFOObacktick space backtickbacktick i.e which renders symmetrical spaces around the backticked word. Also note the double "for" in both the first and the last table columns. There was a problem hiding this comment. My CSS settings got messed up. It should look like this:
|
||
| |2 single hyphens are used for `''bold text''`| (<<.icon $:/core/images/bold>>) |2 single hyphens are used for `<strong>bold text</strong>` |2 single hyphens are used for ''bold text''| | ||
| |2 slashes are used for `//italic text//`| (<<.icon $:/core/images/italic>>) |2 slashes are used for `<em>italic text</em>` |2 slashes are used for //italic text//| | ||
| |2 underscores are used for `__underscored text__`| (<<.icon $:/core/images/underline>>) |2 underscores are used for `<u>underscored text<u>` |2 underscores are used for __underscored text__| | ||
| |2 circumflex accents are used for `^^superscripted^^` text | (<<.icon $:/core/images/superscript>>) |2 circumflex accents are used for `<sup>superscripted</sup>` text |2 circumflex accents are used for ^^superscripted^^ text | | ||
| |2 commas are used for `,,subscripted,,` text | (<<.icon $:/core/images/subscript>>) |2 commas are used for `<sub>subscripted</sub>` text |2 commas are used for ,,subscripted,, text | | ||
| |2 tilde signs are used for `~~strikethrough~~` text | (<<.icon $:/core/images/strikethrough>>) |2 tilde signs are used for `<strike>strikethrough</strike>` text |2 tilde signs are used for ~~strikethrough~~ text | | ||
|
|
||
| ''Special case to show embedded backticks'' | ||
|
|
||
| |Wikitext |HTML |Rendered Output|h | ||
| |<code>``double backticks allows `embedded` backticks``</code>|``<code>double backticks allows `embedded` backticks</code>`` |``double backticks allows `embedded` backticks``| | ||
|
|
||
| </div> | ||
|
|
||
| See also: [[Code Blocks in WikiText]] | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure that we should rearrange these items. The disadvantage is that it makes it much harder to visually scan the list of children to look for a specific entry.
As a general rule, I think it's only advisable to have manual ordering for lists of less than about 7 items.