Skip to content

Commit 8283ef8

Browse files
MasssiveJuice08MasssiveJuice08
committed
Update 'Wiki Style Guide.md'
- renamed to 'Formatting Guidelines' - Nested within new folder 'Manual of Style' which contains - Article Layout Guidelines - Content Guidelines - Formatting Guidelines
1 parent 0f2e534 commit 8283ef8

File tree

5 files changed

+398
-204
lines changed

5 files changed

+398
-204
lines changed

‎content/MMW Design & Planning/Manual of Style/Article Layout Guidelines.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
tags:
3+
- Manual-of-Style
4+
- MMW-Development
5+
description: Guidelines for structuring wiki articles - Part of the Morrowind Modding Wiki Manual of Style
6+
---
7+
8+
> [!infobox]
9+
>
10+
> ## [[MMW Design & Planning/Manual of Style/index.md|Manual of Style]]
11+
>
12+
> ![[PuzzleBoxOnly.png]]
13+
>
14+
> ### This article is part of the [[MMW Design & Planning/Manual of Style/index.md|Manual of Style]]
15+
>
16+
> - [[Article Layout Guidelines]]
17+
> - [[Content Guidelines]]
18+
> - [[Formatting Guidelines]]
19+
20+
## About
21+
22+
TO-DO

‎content/MMW Design & Planning/Manual of Style/Content Guidelines.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
tags:
3+
- Manual-of-Style
4+
- MMW-Development
5+
description: Guidelines for wiki content - Part of the Morrowind Modding Wiki Manual of Style
6+
---
7+
8+
> [!infobox]
9+
>
10+
> ## [[MMW Design & Planning/Manual of Style/index.md|Manual of Style]]
11+
>
12+
> ![[PuzzleBoxOnly.png]]
13+
>
14+
> ### This article is part of the [[MMW Design & Planning/Manual of Style/index.md|Manual of Style]]
15+
>
16+
> - [[Article Layout Guidelines]]
17+
> - [[Content Guidelines]]
18+
> - [[Formatting Guidelines]]
19+
20+
## Style
21+
22+
The Morrowind Modding Wiki differs from other wikis in that it uses an instructional tone for its writing style.
23+
24+
TO-DO

‎content/MMW Design & Planning/Manual of Style/Formatting Guidelines.md

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
---
2+
tags:
3+
- Manual-of-Style
4+
- MMW-Development
5+
description: Guidelines for formatting Markdown text - Part of the Morrowind Modding Wiki Manual of Style
6+
---
7+
8+
> [!infobox]
9+
>
10+
> ## [[MMW Design & Planning/Manual of Style/index.md|Manual of Style]]
11+
>
12+
> ![[PuzzleBoxOnly.png]]
13+
>
14+
> ### This article is part of the [[MMW Design & Planning/Manual of Style/index.md|Manual of Style]]
15+
>
16+
> - [[Article Layout Guidelines]]
17+
> - [[Content Guidelines]]
18+
> - [[Formatting Guidelines]]
19+
20+
## About
21+
22+
Guidelines for formatting Markdown text for the Morrowind Modding Wiki
23+
24+
---
25+
26+
## Code
27+
28+
See [Obsidian 'Basic Editing Syntax'](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Code)
29+
30+
### Inline Code
31+
32+
In addition to denoting code, \``Inline code`\` can be used in the following ways:
33+
34+
- Directory paths, e.g., `C:\Games\OpenMWMods`
35+
- _what else?_
36+
37+
Inline code should not be used to denote keyboard buttons, e.g., `ctrl`. Instead, use `<kbd>` HTML tags like so: `<kbd>ctrl</kbd>`, which is rendered as <kbd>ctrl</kbd>
38+
39+
### Code Blocks
40+
41+
Code blocks support [syntax highlighting](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Code+blocks) by defining code language after the first three backticks, e.g.,
42+
43+
\`\`\`lua
44+
\`\`\`
45+
46+
#### Supported Languagss
47+
48+
Obsidian and Quartz support most coding languages for syntax highlighting.
49+
50+
- [Obsidian supported languages (using Prism)](https://prismjs.com/#supported-languages)
51+
- [Quartz supported languages (using Shiki)](https://shiki.style/languages)
52+
53+
MMW does not yet support MWScript syntax highlighting for Obsidian and Quartz.
54+
55+
### Quartz-Specific Features
56+
57+
Quartz uses Shiki for [Syntax Highlighting](https://quartz.jzhao.xyz/features/syntax-highlighting), which offers many features for styling of both codeblocks _and_ Inline code that are not present in base Obsidan.
58+
59+
These include:
60+
61+
- titles
62+
- line highlighting and word highlighting
63+
- line numbers
64+
- escaping codeblocks
65+
66+
As these features are not part of Obsidian, they will not be rendered there. However, The community plugin [Shiki Highlighter](https://github.com/mProjectsCode/obsidian-shiki-plugin) can be used to enable rendering of these.
67+
68+
---
69+
70+
## Emphasis
71+
72+
Adding emphasis to certain words or phrases helps to draw readers' attention to important details.
73+
74+
Emphasis can be added with either **bold** or **italicized** text. However, it should be used sparingly, as each emphasis added will lessen the effect of other emphases and detract from the appearance of the article.
75+
76+
Emphasis can also be added by the use of Callouts - see [[Formatting Guidelines#Callouts]]
77+
78+
79+
80+
- **Bold** can be used to add emphasis only when it is intended as a **crucial warning** in the body text. However, warnings should generally be emphasized by adding a `> [!warning]` or `> [!danger]` callout instead.
81+
82+
83+
> [!tip]- Practices to Avoid When Emphasizing
84+
>
85+
> #### Do not do the following:
86+
>
87+
> - Add emphasis with 'single' or "double" quotation marks
88+
> - Use ALL CAPS for emphasis.
89+
> - Use _**double emphasis**_ by both holding and italicizing a word or phrase.
90+
> - Do not overemphasize, as each emphasis added will lessen the effect of other emphases and detract from the appearance of the article
91+
92+
### Bold
93+
94+
- Use \*\***double Asterisks**\*\* instead of \_\___double underscores__\_\_ to define bold words/characters. This makes it easier to differentiate them from \__italic_\_ words/characters at a glance when editing
95+
- Bold the article name the first time it appears in the page's introductory sentence. Any alternative names in the introductory sentence should also be bolded. (e.g. "**Mlox** is a tool for sorting plugin load order.")
96+
- Bold the word or phrase being defined in bulleted or numeric lists.
97+
- Do not use bold for general emphasis; use italics instead.
98+
99+
> [!example]-
100+
>
101+
> ### Mlox
102+
>
103+
> - **Sorting plugin load order** is the main use of Mlox.
104+
> - **Mod conflicts** can be identified by mlox through the use of `[conflict]` rules.
105+
> - **Requirements** can be stipulated by Mlox by way of `[requires]` rules to notify users if they are missing plugins required by others
106+
107+
### Italics
108+
109+
- Use \__underscores_\_ instead of \**asterisks*\* to define italics. This makes it easier to differentiate them from \*\***bold**\*\* words/characters at a glance when editing.
110+
- Italics should be used for the titles of books, games and non-MMW Morrowind modding guides (such as _Notes for Modmakers_) This includes the titles of _Elder Scrolls_ games and expansion packs, even when only the subtitle (e.g. _Oblivion_, _Skyrim_, _Online_) is written. The name of the series, _The Elder Scrolls_, should be italicized as well (even when shortened to just _Elder Scrolls_). Initialisms, most notably ESO, are not italicized.
111+
- Italics can be used for general emphasis, but should be used sparingly.
112+
113+
> [!info]
114+
>
115+
> By default, Obsidian uses \*asterisks\* to denote italics when using the `Toggle italic` hotkey[^1]. Instead, use <kbd>shift</kbd>+<kbd>_</kbd>, which automatically wraps a word in \_underscores\_
116+
117+
---
118+
119+
## Headers
120+
121+
122+
Headers structure content to help readers navigate your article.
123+
124+
> [!abstract]+ Headers
125+
>
126+
> ## \#\# This is a main subject (h2)
127+
>
128+
> ### \#\#\# This subject has several important sub-subjects (h3)
129+
>
130+
> #### \#\#\#\# Sub-subjects can benefit from subheadings (h4)
131+
>
132+
> ##### \#\#\#\#\# Example (h5)
133+
>
134+
> ```
135+
> [example code block]
136+
> ```
137+
138+
**Header 1** (H1) should never be used, as a webpage should only ever contain one H1 element - in Quartz, the article filename is the H1 element (i.e., **Wiki Formatting Guidelines**)
139+
140+
| Markdown | HTML Header Tag Equivalent | Use |
141+
| ----------------- | -------------------------- | ------------------------------------------------- |
142+
| \# | `<h1>` | Unused, as Quartz uses the filename as h1 |
143+
| \#\# | `<h2>` | Main section divider |
144+
| \#\#\# - \#\#\#\# | `<h3>` - `<h4>` | For use in article subsections |
145+
| \#\#\#\#\# | `<h5>` | For labeling _'Example'_ above fenced code blocks |
146+
147+
Header numbers should be arranged sequentially.
148+
149+
- This improves readability by providing a logical structure
150+
- Improves website SEO by making it easier for search engines to index the website's content
151+
152+
> [!example]-
153+
>
154+
> > [!success] Correct
155+
> >
156+
> > ```
157+
> > - H1
158+
> > - H2
159+
> > - H3
160+
> > - H4
161+
> > ```
162+
>
163+
> > [!success] Correct
164+
> >
165+
> > ```
166+
> > - H1
167+
> > - H2
168+
> > - H3
169+
> > - H2
170+
> > - H3
171+
> > - H4
172+
> > - H2
173+
> > ```
174+
>
175+
> > [!failure] Incorrect
176+
> >
177+
> > ```
178+
> > - H1
179+
> > - H3
180+
> > - H2
181+
> > - H4
182+
> > ```
183+
184+
---
185+
186+
## Line-Wrapping
187+
188+
Do not 'hard-wrap' lines. This is unneeded in Obsidian which renders line-wrapping automatically according to window size, as does Quartz.
189+
190+
'Hard-wrapping' is intentionally adding a line-break after a certain amount of characters, e.g., after 80 characters.
191+
192+
---
193+
194+
## Links
195+
196+
Links are important for navigating content in the wiki.
197+
198+
\[\[Wikilinks\]\] are used for linking between different pages in the wiki, as well as for embedding content such as images.
199+
200+
> [!info]+ Internal Links
201+
>
202+
> An 'internal link' is a link from one page in MMW to another page in MMW.
203+
>
204+
> These should be rendered using \[\[Wikilink\]\] format as detailed on [Internal Links - Obsidian Help](https://help.obsidian.md/Linking+notes+and+files/Internal+links)
205+
206+
> [!info]+ External Links
207+
>
208+
> Use Markdown to link to another site:
209+
>
210+
> ```
211+
> [insert link display text](https://websiteurl.com)
212+
> ```
213+
214+
### When to Use Links
215+
216+
This can be summarised with three principles:
217+
218+
- **Visual clarity**: Avoid cluttering links
219+
- **Relevance**: Ensure links are relevant to the content of the article
220+
- **First-come**, first-served: Only the first mentioned instance should contain a link
221+
222+
#### Visual Clarity
223+
224+
Creating too many links can distract the reader and make the article hard to read; some readers are likely to pause on each link to determine whether the link is of interest.
225+
226+
Be sure that any link you add will help readers and be used by readers.
227+
228+
#### Relevancy
229+
230+
Ensure links to other pages are relevant to the article at hand.
231+
232+
From UESP:
233+
234+
> _It makes little sense to link to an article about Orcs whenever you mention Orcish Armor. If anything, you'd want to link to a page describing the armor, not Orcs in general._
235+
> – [UESP: Style Guide](https://en.m.uesp.net/wiki/UESPWiki:Style_Guide)
236+
237+
#### First-Come, First-Served
238+
239+
In each article, only the first mentioned instance of a link-worthy topic should contain the link. Additional mentions in the same article should not contain a link.
240+
241+
This helps to prevent cluttering links and breaking the flow of an article.
242+
243+
---
244+
245+
## Lists
246+
247+
Lists are particularly useful for guides and tutorials, which make up the majority of content on the wiki. Unnumbered lists or 'bullet points' help to organize and emphasize information quickly and effectively, while ordered lists (i.e., numbered lists) are useful for useful for step-by-step sections of tutorials.
248+
249+
### Unnumbered Lists
250+
251+
Use hyphens `-` for defining unnumbered lists and sub-lists, instead of asterisks `*`. This is to differentiate unnumbered lists from \*\***bold**\*\* words/characters.
252+
253+
### Ordered Lists
254+
255+
Obsidian and Quartz support ordered lists styled with Arabic numerals (1, 2, 3).
256+
257+
1. Use `1.` Rather than `1)` to denote an ordered list.
258+
2. Obsidian and Quartz do not support ordered lists styled with letters or Roman numerals.
259+
260+
---
261+
262+
## Page Breaks
263+
264+
Use `---` to define a page break.
265+
266+
Page breaks should only be added at the end of an \#\# H2 heading section, not after \#\#\# H3 or more subheading sections.
267+
268+
> [!example]-
269+
>
270+
>> [!success]+ Correct
271+
>>
272+
>> ## H2 Heading
273+
>>
274+
>> \[content\]
275+
>>
276+
>> ### H3 Subheading
277+
>>
278+
>> \[content\]
279+
>>
280+
>> #### H4 Subheading
281+
>>
282+
>> \[content\]
283+
>>
284+
>> ---
285+
>>
286+
>> ## H2 Heading
287+
>
288+
>> [!failure]+ Incorrect
289+
>>
290+
>> ## H2 Heading
291+
>>
292+
>> \[content\]
293+
>>
294+
>> ---
295+
>>
296+
>> ### H3 Subheading
297+
>>
298+
>> \[content\]
299+
>>
300+
>> ---
301+
>>
302+
>> #### H4 Subheading
303+
>>
304+
>> \[content\]
305+
>>
306+
>> ---
307+
>>
308+
>> ## H2 Heading
309+
310+
311+
---
312+
313+
## Tables
314+
315+
Tables are easy to read; please use these whenever possible for listing data such as script functions (e.g., MWSE-Lua), modding tool commands (e.g., Tes3cmd commands), or in-game statistics.
316+
317+
> [!tip] Tip: Use 'Live Preview' Mode for Editing Tables
318+
>
319+
> 'Live Preview' mode in Obsidian simplifies editing tables with a number of features:
320+
>
321+
> - Add/delete column or row
322+
> - Move row up/down, or column left/right
323+
> - <kbd>shift</kbd>+<kbd>enter</kbd> automatically adds a `<br>` HTML tag to add a new line within a single table cell.
324+
>
325+
> Additionally, editing tables in Live-Preview will proportionally space apart vertical bars (`|`) and hyphens (`-`) in the plaintext Markdown, improving readability in Source Mode or when viewing the Markdown in Github.
326+
327+
[^1]: Default hotkey to toggle italics is <kbd>shift</kbd>+<kbd>i</kbd>

0 commit comments

Comments
 (0)