Complexity can only be conquered through composition. Reducing large ideas into smaller components is critical for comprehension, and easy navigation of these components is just as important. Obtaining both of these properties makes large information sets magnitudes easier to traverse and digest.
There are a few general BBcode resources available elsewhere on this forum, including BBCode FAQ and Marco's more site specific BBCodes Overview and Usage. A deeper dive into how BBCode operates can be seen here at this Wikipedia Article. These give a good sense of base functionality, however, applying them effectively is still quite a challenge.
The ability to link not only outside the document, but to locations within itself, is incredibly useful. It is something I use heavily (especially in Crafting Compendium) to keep information organized and sub-sections directly linkable.
New Crafting Compendium for 1.5 when?
Table of Contents
1 - Document Presentation
- 1.1 - Headers
1.2 - Inter-Page Linking
1.3 - Font-Awesome
1.4 - Links + Font Awesome
1.5 - BBCode & Newlines
3 - Final Comments
1 - Document Presentation
Section Contents
1.1 - Headers
1.2 - Inter-Page Linking
1.3 - Font-Awesome
1.4 - Links + Font Awesome
1.5 - BBCode & Newlines
1.1 - Headers
Header tags in HTML help give structural meaning to various sections of the document. The forum code automatically applies styling to
h#
tags. While not immediately obvious: this is a huge bonus for post authors and the community. Standard styling promotes universal familiarity, readers will have a much easier time identifying and navigating through posts regardless of the content topic. Because of this, it is wise to use h#
tags as section titles instead of manual text styling (large size + bold, color, etc).HTML natively defines 6 Header elements: <h1>-<h6>. Here is a quick test to show how these BBCode heading tags get translated:
BBCode:
Code: Select all
----------------------------------------
[h1]h1 Test[/h1]
[h2]h2 Test[/h2]
[h3]h3 Test[/h3]
[h4]h4 Test[/h4]
[h5]h5 Test[/h5]
[h6]h6 Test[/h6]
----------------------------------------
HTML Output:
----------------------------------------[h1]h1 Test[/h1]
h2 Test
h3 Test
h4 Test
[h5]h5 Test[/h5]
[h6]h6 Test[/h6]
----------------------------------------
Conclusion:
Due to technical limitations, onlyh2
- h4
get translated into HTML. This limits section hierarchies (categorical depths) with predefined heading elements to only three tiers. A quick summary:Code: Select all
BBCode Tags HTML Output Usable? Underline?
---------------- ---------------- ------- ----------
[h1]h1 Test[/h1] [h1]h1 Test[/h1] No -
[h2]h2 Test[/h2] <h3>H2 TEST</h3> Yes Yes
[h3]h3 Test[/h3] <h4>h3 Test</h4> Yes No
[h4]h4 Test[/h4] <h5>H4 TEST</h5> Yes No
[h5]h5 Test[/h5] [h5]h5 Test[/h5] No -
[h6]h6 Test[/h6] [h6]h6 Test[/h6] No -
► Output Inconsistency
1.2 - Inter-Page Linking
Browsers can follow links that target the current page, scrolling the window to a specific location and adding a hashtag suffix to the URL: website.com/page#inter-page-link. This also adds a location history record into the browser (for
Back/Forward
buttons)These inter-page links give readers an opportunity to access sub-sections of the page directly. These links exist in the global page scope, which means they will work between multiple posts on the same page, great for situations where reserved posts are utilized.
HTML uses anchor tags (<a>) for linking. BBCode uses
navlink
and navtarget
tags to setup inter-page linking, and url
tag for external-page linking. These ultimately get transformed into HTML tags.The example below shows the syntax for these tags. Note that
navlink
includes an equals sign (=) within the opening tag to define where the link will point to, while navtarget
does not:My Heading
To Heading
Code: Select all
[navtarget]my-anchor-id[/navtarget]My Heading
[navlink=my-anchor-id]To Heading[/navlink]
1.3 - Font-Awesome
This forum has Font Awesome v4.5.0 installed. Icons can be included by enclosing an icon name within an opening and closing
[fa]
tags.There are a wide variety of icons for nearly any situation (Copy/Paste fails; find the icon
fa-
id below by Right-Clicking it, and select "Inspect"):- Quantification: / / /
Narrative Aid:
Selections:
Navigation:
Font-Awesome Cheatsheet shows all available icons for v4.7.0. While looking through the list, any icons marked with a number above
4.5
are not available (version dependency shows up to the right of the name). The cheatsheet page prefixes icons with fa-
, do not include this prefix in the BBCode tag:Code: Select all
Cheatsheet phpBB Post Usable?
----------------------------- ---------------- -------
fa-fire [] [fa]fire[/fa] Yes
fa-firefox [] 4.4 [fa]firefox[/fa] Yes
fa-gitlab [] 4.6 [fa]gitlab[/fa] No
fa-telegram [] 4.7 [fa]telegram[/fa] No
1.4 - Links + Font Awesome
Since the navlink tag encloses text, Font Awesome icons can be used as the text for inter-page links or external links. These sweet graphics not only add style points; they reduce page clutter and help provide language-independent navigation elements:
Heading
Code: Select all
[navtarget]link-fa-ex[/navtarget]
[h2]Heading [navlink=link-fa-ex][fa]link[/fa][/navlink] [navlink=fa-links][fa]arrow-up[/fa][/navlink] [url=https://en.wikipedia.org/wiki/Font_Awesome][fa]wikipedia-w[/fa][/url][/h2]
1.5 - BBCode & Newlines
BBCode's translation from tags to HTML seems to enjoy secretly insert extra blank lines into your beautiful design. This issue usually occurs with BBCode tags that alter the positioning of elements, like
align
, hr
, and code
. During the translation to HTML, extra <br> tags are magically inserted without your consent. An identical operation happens when you press the Enter
button in the text editor (but, you know, when you asked for it).This means that pressing
Enter
after some BBCode tags will end up producing two HTML <br> elements, which is what causes mysterious gaps. Extra text gaps can be extremely frustrating, and may seem potentially unfixable. The good news is that these formatting issues can be resolved with some unintuitive BBCode formatting.The
hr
tag produces a horizontal line; helpful for grouping/separating information, and exposes this issue more glaringly than other tags. A fix for this issue is shown below in a sequence of three steps, A, B, and C. Each step has three sub-sections explaining what's happening - BBCode, HTML Output, and Conclusion:========== Step A: Unforeseen Consequences ==========
Nicely formatted text editor layout. Everything should look exactly the same when I hit Submit...
BBCode:
Code: Select all
----------------------------------------
Line 1
[hr][/hr]
[navtarget]my-target[/navtarget]
[align=center]Line 3[/align]
Line 2
----------------------------------------
HTML Output:
----------------------------------------
Line 1
Line 3
Line 2
----------------------------------------
Conclusion:
The text looked tightly grouped in the editor, but then it spits out a bunch of gaps. The
navtarget
(<a>) isn't even a visible element, so should have no affect on the layout! We will have to adjust the text in the editor.========== Step B: Apprehension ==========
But the editor code looked so nice. Fixes will end up butchering MY formatting!
BBCode:
Code: Select all
----------------------------------------
Line 1
[hr][/hr]
[navtarget]my-target[/navtarget]
[align=center]Line 3[/align]Line 2
----------------------------------------
HTML Output:
----------------------------------------
Line 1
Line 3Line 2
----------------------------------------
Conclusion:
By relocating 'Line 2' text up after the '[/align]', it closed the extra gap. We need to keep joining lines in the editor where we see extra gaps, like the two between the '[hr]' and 'Line 3'...
========== Step C: Xen ==========
With so much destruction, is peace still an option?
BBCode:
Code: Select all
----------------------------------------
Line 1
[hr][/hr] [navtarget]my-target[/navtarget] [align=center]Line 3[/align]Line 2
----------------------------------------
HTML Output:
----------------------------------------
Line 1
Line 3Line 2
----------------------------------------
Conclusion:
It finally matches expectations of Step A! All it took was a couple theoretical crowbar swings at the editor formatting! Consider fixing all the minor formatting issues after the majority of content is written, as the 'fixed' BBCode text is far less comprehensible.
2 - Document Structure
Section Contents
2.1 - Categorization
2.2 - Navigation Structure
2.3 - Table of Contents
2.4 - Section Headings
2.1 - Categorization
Documents tend to form branching structures of categorized information. Most trivial documents don't warrant much structural planning and navigational aid. With instructional documents, this concept quickly becomes indispensable as the content expands.
Offering navigation throughout a document reduces time spent traversing content for both new and returning readers. The two types of category complexity discussed throughout this document are Flat Hierarchies (single depth) and Nested Hierarchies (multiple depths):
Flat Hierarchy
Example Categorization:
Code: Select all
Document
├── Stats
├── Skills
├── Gear
├── Leveling
├── Ubers
├── Farming
└── Conclusion
Nested Hierarchy
Example Categorization:
Code: Select all
Document
├── Stats
├── Skills
│ ├── Support Tree
│ ├── Damage Tree
│ └── Reward Skills
├── Gear
│ ├── Early Game
│ ├── Mid Game
│ └── End Game
├── Leveling
│ ├── Early Game
│ ├── Mid Game
│ └── End Game
├── Ubers
├── Farming
└── Conclusion
Choosing how to nest various sections requires a bit of commonality analysis. As long as the category information remains consistent, there really is no wrong way to organize information. An alternative structure to the above:
Code: Select all
Document
├── Stats
├── Skills
├── Early Game
│ ├── Gear
│ ├── Leveling
│ └── Skills
├── Mid Game
│ ├── Gear
│ ├── Leveling
│ └── Skills
├── End Game
│ ├── Gear
│ ├── Leveling
│ └── Skills
├── Ubers
├── Farming
└── Conclusion
2.2 - Navigation Structure
Since websites generally only use two dimensions (x and y) for displaying information, this inherently limits our navigation elements with two orientations: Horizontal and Vertical. Horizontal takes up less space, while Vertical soaks up more space by using multiple horizontal rows of space.
Centering text is typically used with Horizontal layout orientations. Vertical lists that use indentation for structure look far better when aligned at the left edge. Various combinations of positioning and layout orientation are explored with example BBcode in the Section Headings section.
Horizontal Orientation
Stats • Skills • Gear • Leveling • Ubers • Farming • Conclusion
Code: Select all
[align=center][navlink=stats]Stats[/navlink] • [navlink=skills]Skills[/navlink] • [navlink=gear]Gear[/navlink] • [navlink=leveling]Leveling[/navlink] • [navlink=ubers]Ubers[/navlink] • [navlink=farming]Farming[/navlink] • [navlink=conclusion]Conclusion[/navlink][/align]
Vertical Orientation
Stats
Skills
Gear
Leveling
Ubers
Farming
Conclusion
Code: Select all
[navlink=stats]Stats[/navlink]
[navlink=skills]Skills[/navlink]
[navlink=gear]Gear[/navlink]
[navlink=leveling]Leveling[/navlink]
[navlink=ubers]Ubers[/navlink]
[navlink=farming]Farming[/navlink]
[navlink=conclusion]Conclusion[/navlink]
Nested Vertical Orientation
1 - Stats
2 - Skills
3 - Early Game
4 - Mid Game
5 - End Game
6 - Ubers
7 - Farming
8 - Conclusion
Code: Select all
[navlink=stats]1 - Stats[/navlink]
[navlink=skills]2 - Skills[/navlink]
[navlink=early-game]3 - Early Game[/navlink]
[list]
[navlink=early-leveling]3.1 - Leveling[/navlink]
[navlink=early-skills]3.2 - Skills[/navlink]
[navlink=early-gear]3.3 - Gear[/navlink]
[/list]
[navlink=mid-game]4 - Mid Game[/navlink]
[list]
[navlink=mid-leveling]4.1 - Leveling[/navlink]
[navlink=mid-skills]4.2 - Skills[/navlink]
[navlink=mid-gear]4.2 - Gear[/navlink]
[/list]
[navlink=end-game]5 - End Game[/navlink]
[list]
[navlink=end-leveling]5.1 - Leveling[/navlink]
[navlink=end-skills]5.2 - Skills[/navlink]
[navlink=end-gear]5.3 - Gear[/navlink]
[/list]
[navlink=ubers]6 - Ubers[/navlink]
[navlink=farming]7 - Farming[/navlink]
[navlink=conclusion]8 - Conclusion[/navlink]
2.3 - Table of Contents
A Table of Contents is always recommended for documents with more than a few categories. The choice between horizontal or vertical orientated elements depends on a few variables. Visual preference is a major factor. Keep in mind that highly nested category structures can be reduced to just one or two depths in the Table of Contents display. Prefixing numerical identifiers in the ToC and Headings can give readers easy reference markers while scrolling the page.
Layout and code examples for a ToC can be seen in the previous Horizontal, Vertical, and Nested sections.
2.4 - Section Headings
Chosing which icons or text will represent navigation queues is subjective; a solid setup for headers is to use for parent category, and for self-reference. This strategy works well for any depth of section headings.
Displaying these elements together in a cohesive manner becomes a bit more challenging. Variations of text alignment and layout orientation for Flat Hierarchy and Nested Herarchy layouts are showcased below:
Flat Hierarchy
All items underneath the same parent topic should offer a consistent linking back to the parent. If the document's information structure consists of:
Code: Select all
Document (Table of Contents)
├── Stats (Link to Self and T.o.C.)
├── Skills (Link to Self and T.o.C.)
├── Gear (Link to Self and T.o.C.)
├── Leveling ... etc ...
├── Ubers
├── Farming
└── Conclusion
Every heading should point back to ToC. Left-Aligned and Centered positioning work equally as well for a simple category tree:
Left-Aligned Headings
Skills
My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
Gear
My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
...
Code: Select all
[navtarget]skills[/navtarget]
[h2]Skills [navlink=skills][fa]link[/fa][/navlink] [navlink=toc][fa]arrow-up[/fa][/navlink][/h2]
My Example Section Content...
[navtarget]gear[/navtarget]
[h2]Gear [navlink=gear][fa]link[/fa][/navlink] [navlink=toc][fa]arrow-up[/fa][/navlink][/h2]
My Example Section Content...
...
Centered Headings
Skills My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
Gear My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
...
Code: Select all
[navtarget]skills[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink] Skills [navlink=skills][fa]link[/fa][/navlink][/h2][/align]My Example Section Content...
[navtarget]gear[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink] Gear [navlink=gear][fa]link[/fa][/navlink][/h2][/align]My Example Section Content...
...
Nested Hierarchy
Same concept as the Flat hierarchy, just... deeper. If the document's category structure consists of:
Code: Select all
Document (Table of Contents)
├── Stats (Link to Self and T.o.C.)
├── Skills (Link to Self and T.o.C.)
├── Early Game (Link to Self and T.o.C.)
│ ├── Leveling (Link to Self and Early-Game )
│ ├── Skills (Link to Self and Early-Game )
│ └── Gear (Link to Self and Early-Game )
├── Mid Game (Link to Self and T.o.C.)
│ ├── Leveling (Link to Self and Mid-Game )
│ ├── Skills (Link to Self and Mid-Game )
│ └── Gear (Link to Self and Mid-Game )
├── End Game ... etc ...
│ ├── Leveling
│ ├── Skills
│ └── Gear
├── Ubers
├── Farming
└── Conclusion
Each child of a parent topic will link to their parent as usual, with theses parent's parent and siblings linking back to their parent, repeating all the way back up to the ToC. This relative linking scheme helps keep consistency throughout the hierarchy tiers.
Variations of alignment and orientation offer some interesting layout choices. Fully Left-Aligned Vertical, fully Centered Horizontal, and mixing Centered Horizontal Heading with Left-Aligned Subheadings are a few instances explored below.
Left-Aligned Vertical Heading with Left-Aligned Subheadings
3 - Early Game
Section Contents
3.1 - Leveling
3.2 - Skills
3.3 - Gear
3.1 - Leveling
My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
3.2 - Skills
My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
...
Code: Select all
[navtarget]early[/navtarget]
[h2]3 - Early Game [navlink=early][fa]link[/fa][/navlink] [navlink=toc][fa]arrow-up[/fa][/navlink][/h2]
[u]Section Contents[/u]
[navlink=early-lvl]3.1 - Leveling[/navlink]
[navlink=early-sk]3.2 - Skills[/navlink]
[navlink=early-gear]3.3 - Gear[/navlink]
[navtarget]early-lvl[/navtarget]
[h3]3.1 - Leveling [navlink=early-lvl][fa]link[/fa][/navlink] [navlink=early][fa]arrow-up[/fa][/navlink][/h3]
My Example Section Content...
[navtarget]early-sk[/navtarget]
[h3]3.2 - Skills [navlink=early-sk][fa]link[/fa][/navlink] [navlink=early][fa]arrow-up[/fa][/navlink][/h3]
My Example Section Content...
...
Centered Horizontal Heading with Centered Subheadings
Early Game
Leveling • Skills • Gear
Leveling My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
Skills My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
...
Code: Select all
[navtarget]early[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink] Early Game [navlink=early][fa]link[/fa][/navlink][/h2][/align]
[align=center][navlink=early-lvl]Leveling[/navlink] • [navlink=early-sk]Skills[/navlink] • [navlink=early-gear]Gear[/navlink][/align]
[navtarget]early-lvl[/navtarget]
[align=center][h3][navlink=early][fa]arrow-up[/fa][/navlink] Leveling [navlink=early-lvl][fa]link[/fa][/navlink][/h3][/align]My Example Section Content...
[navtarget]early-sk[/navtarget]
[align=center][h3][navlink=early][fa]arrow-up[/fa][/navlink] Skills [navlink=early-sk][fa]link[/fa][/navlink][/h3][/align]My Example Section Content...
...
Centered Horizontal Heading With Left-Aligned Subheadings
Early Game
Leveling • Skills • Gear
Leveling
My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
Skills
My example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content my example section content
...
Code: Select all
[navtarget]early[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink] Early Game [navlink=early][fa]link[/fa][/navlink][/h2][/align]
[align=center][navlink=early-lvl]Leveling[/navlink] • [navlink=early-sk]Skills[/navlink] • [navlink=early-gear]Gear[/navlink][/align]
[navtarget]early-lvl[/navtarget]
[h3]Leveling [navlink=early-lvl][fa]link[/fa][/navlink] [navlink=early][fa]arrow-up[/fa][/navlink][/h3]
My Example Section Content...
[navtarget]early-sk[/navtarget]
[h3]Skills [navlink=early-sk][fa]link[/fa][/navlink] [navlink=early][fa]arrow-up[/fa][/navlink][/h3]
My Example Section Content...
...
3 - Final Comments
With any creative process, there is no objective best way to accomplish a goal. Just be sure to be consistent with semantics; use tags, colors, and text formatting to represent the same idea (or signal a certain type of value) throughout the entire document.
I tend to take a minimalist approach when translating an idea into a consumable format. The quote “Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.” is always bouncing around in the back of my mind.
As this document evolves, constructive criticism is welcome.
Random Side-Note: The Crafting Compendiums
navtarget
identifiers are numbers (1-1-1). However, I would rather they be words describing the sections, but the Crafting Compendium is so large it ran out of room (59917/60000 characters). So the numbers were a compromise.Contributions
Big thanks to those who contributed constructive criticism and suggestions: