zaliel.sel | 2021-09-20 23:53:28 UTC | #1
# Introduction [Discourse](https://www.discourse.org/) is a forum-like platform designed to allow communities come together and share their knowledge, work problems, and even have fun. While Discourse will be like many forums you may have used before, there are some distinctions. # Structure Discourse is designed with a Category / Topic structure. Simply put, a Category is a collection of posts, which Discourse calls Topics. Topics may be a single post (the Original Post or OP for short) or have many replies. Categories may have Subcategories, as well. Always be mindful of where you are posting to ensure your content is seen by the right audiences. If you ever create a topic by mistake, simply contact the Admins or Moderators to have them deleted. # Content Styling Discourse supports many different style languages, including: HTML, BBCode, and Markdown. For a complete rundown of the various syntax commands you can use, please refer to the following Unofficial Guide [copied from this website.](https://forum.digikey.com/t/an-unofficial-discourse-user-reference-guide/1125/1) *** [Copied from this guidebook](https://forum.digikey.com/t/an-unofficial-discourse-user-reference-guide/1125/1) This is a “quick” how-to guide for using [Discourse ](https://www.discourse.org/) forum/community software. It contains a majority of the common features available to users/content editors, but may not have complete coverage of the featureset. If anyone sees anything to add or correct, feel free to comment. If you’d like to learn more about the Discourse Editor’s syntax take a look at the [commonmark](http://commonmark.org/help/) (a flavor of markdown) docs for more info. ### Links Most of the time you'd want to use the editor bar ![image|1x1](upload://v30S3699WbfCWzSdEdc1wsCCxYc.png) or hotkey crtl+k, but the basic format is `[link text](https://www.ussbrahe.org)` which will give you an example link that looks like this: [link text](https://www.ussbrahe.org) > **Note - Easier Editing with Links** > Having long URLs intermingled in your editor can sometimes make it a pain so you can also offset the links using the syntax in the example below. Note you must have a blank line above the reference and the reference id can be any number, text, or punctuation. ``` This paragraph is much easier to read in the [editor][1] because you can [include][dklink] the links below the paragraph text or at the bottom of the page. [1]: https://www.ussbrahe.org/t/recruitment/37 [dklink]: https://www.ussbrahe.org/ ``` This paragraph is much easier to read in the [editor](https://www.ussbrahe.org) because you can [include ](https://www.ussbrahe.org) the links below the paragraph text or at the bottom of the page. [1]: https://github.com/digikey/digikey-kicad-library [dklink]: https://www.ussbrahe.org ### Images Adding images is quite easy, if there's an image in your clipboard, just paste it in, the forum will automatically upload the image and fill in the appropriate syntax to make the image appear. If you are linking an image which is already on the web, use the following syntax. `![title text](https://i.imgur.com/b0abKrxb.png)` Result: ![title text](https://i.imgur.com/b0abKrxb.png) ##### Image Sizing If you would like to resize a large image to a smaller image use the following syntax. ``` ![Original|200x200](https://i.imgur.com/b0abKrxb.png) ![Percent|200x200, 50%](https://i.imgur.com/b0abKrxb.png) ![By Pixels|64x64](https://i.imgur.com/b0abKrxb.png) ``` Original ![robot arm|200x200](https://i.imgur.com/b0abKrxb.png) Resized 50% ![robot arm|100x100](https://i.imgur.com/b0abKrxb.png) By Pixels ![robot arm|64x64](https://i.imgur.com/b0abKrxb.png) ### Text Formatting For bold, italics and strike-through use the editor buttons ![image|56x28](upload://hXh7Pytnmt1jqZj6QiZxfWqhSZT.png) or directly type the markdown: ``` **bold word** or __bold word__ *italicized word* or _italicized word_ _combo of **bold** and **italic**_ ~~strike-through word~~ ``` **bold word** or **bold word** *italicized word* or *italicized word* *combo of **bold** and **italic*** ~~strike-through word~~ Alternatively, there’s some BBCode sytnax that a person can use `[b]like this[/b]` like this `[i]or this[/i]` or this `[u]underline[/u]` underline Font color is not natively supported, but there is a BBCode plugin that will allow for changes in font color. One can also have some choice to change fonts or colors using the LaTeX-based mathjax plugin covered in the mathjax section of this guide. `$\color{red}{red text}$` redtext ## Headings ``` # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 horizontal rule is 3+ asterisks *** ``` ![image|50x288](upload://3gxIsAZmPlTfrdfAAEIxDbouupP.png) _horizontal rule_ *** ### Lists You can use the editor buttons for ordered![image|23x21](upload://mzVrWSGg4dQs86lN2XwhenWaeKw.png) or unordered ![image|26x21](upload://reFFAKe8AbBE4QBsHscHJOSic15.png) lists. ``` 1. First ordered list item 2. second list item * sub-lists are offset by three spaces 1. Specific numbers 1. don't matter they will auto increment 1. auto increment * unordered lists * are also possible ``` 1. First ordered list item 2. Explicit second list item * sub-lists are offset by three spaces 3. Specific numbers 4. don’t matter they will auto increment 5. auto increment * unordered lists * are also possible ### Code Formatting #### Inline code formatting Surround a section of code with backticks (`) inline code formatting. **Typing:** `var x = 10;` **Results in:** `var x = 10;` This can also be done as `var x = 10;` inline. Present entire line as code by prefixing four (4) spaces (an extra newline before this) **Typing** : var this = “is a line”; **Results in :** ``` var this = "is a line"; ``` #### Multi-Line Blocks of Code Surrounding code with three backticks ``` will allow for code to span multiple lines **Typing:** ``` function foo(bar){ return bar+1; } ``` **Results in:** ``` function foo(bar){ return bar+1; } ``` #### Syntax Highlighting The code block will try to automatically choose a style for code, but you can explicitly call out the desired formatting. ```javascript function foo(bar){ return bar+1; } ``` **Results in:** ``` function foo(bar){ return bar+1; } ``` ### Tables Tables are second class citizens in Discourse, some of the formatting features and niceties work and some don’t. > **Protip -** The easiest way to get a table into discourse is to start a table in an spreadsheet, then copy & paste that table into the editor window. Discourse natively handles the format change and makes creating a table much easier. Excel and Google Sheets work great using this method. A markdown table in Discourse needs at least the first two lines to exist: ``` |Color|Weight|Height| |-|-|-| |red|12|160| |green|4|100| ``` |Color|Weight|Height| | --- | --- | --- | |red|12|160| |green|4|100| You can also use **HTML for tables** . ```
Color Weight Height
red 12 160
green 4 100
``` |Color|Weight|Height| | --- | --- | --- | |red|12|160| |green|4|100| ## Blockquotes Blockquotes can be found in the editor bar button ![image|29x23](upload://6ifegltWooJEjdhREi4kqUy1kWt.png) Puting a greater than sign > in front of so a line will create blockquotes **Typing:** > this is some blockquoted text > this is another line of blockquoted text this is not blockquoted > this is another one **Results in:** > this is some blockquoted text > this is another line of blockquoted text this is not blockquoted > this is another one ## Table of Contents ### Plugin Approach You can automatically create a Table of Contents by selecting "Insert Table of Contents" in the editor's cogwheel menu like so: ![image|690x70](upload://3l8needCL8BiJu3lGx5QLCtCV52.png) Make sure this `
` is on the first line of the post _and_ there is an empty line between it and your content. ```html
# Introduction ``` You'll know it is configured correctly if you see this message inside the editor window: ![image|690x70](upload://3l8needCL8BiJu3lGx5QLCtCV52.png) ### Manual Approach This is not a native feature of Discourse, you can manually create a TOC by using HTML headings with the appropriate ID rather than the `##` heading sytnax. Make sure your id is prefixed with `heading--` , this is necessary because of the Discourse’s javascript app based architecture. Here is a quick example: ``` - [link to first heading](#heading--first-header) - [link to second heading](#heading--second-header) - [link to third heading](#heading--third-header) - [link to fourth heading](#heading--fourth-header)

First One

some text

Second One

more text

Third One

even more text

Fourth One

ok no more text ``` * [link to first heading](https://www.ussbrahe.org/t/discourse-tips-tricks/73/1#heading--first-header) * [link to second heading](https://www.ussbrahe.org/t/discourse-tips-tricks/73/1#second-header) * [link to third heading](https://www.ussbrahe.org/t/discourse-tips-tricks/73/1#heading--third-header) * [link to fourth heading](https://www.ussbrahe.org/t/discourse-tips-tricks/73/1#heading--fourth-header) ### First One some text ### Second One more text ### Third One even more text ### Fourth One ok no more text ## Using LaTeX for Formatted Math This section describes a plugin not installed on our server and therefore does not display properly. It is preserved as part of the original guide in the event we ever implement it. If the Mathjax plugin is desired, please open a Technical Support Topic. [details="Mathjax & LaTeX"] The is an official Discourse plugin that uses Mathjax to enable LaTeX based formatting. The LaTeX syntax is a beast on it’s own so I’ll only point out a few examples. Look at the [quick reference guide ](https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference) on stack exchange for more information. The basic usage is to use `$ \some inline latex expression $` or to express in multi-line surround the LaTeX with `$` . ``` $ H(z)&=\sum_{k=0}^{\infty}{(k+1)z^{-k}}\\ &=\frac{z^2}{(z-1)^{2}} \end{align} $ ``` H(z)=∞∑k=0(k+1)z−k=z2(z−1)2 There is color text and a variety of symbols( αωγβΩΓ ), fonts available( HELLOWORLD ), and other ways to express things (((((x))))) *** ## Using HTML ### Other If you’d ever like to see how someone else created their post you can use the following URL format to view the raw markdown `https://forum.example.com/raw/{topicid}/{postid}` take a look at [the current post](https://www.ussbrahe.org/raw/73) as an example. ### Aligning items If you’re trying to align images or wrap text, there isn’t a really great tools for either of these things. It’s possible with custom plugins, but it’s not yet supported in native Discourse. [/details] # Private Messages A Private or Private Group Message are types of Topics that intended to only be seen by the recipients. In every way that matters (formatting, policy), a Private Message is like a Topic _except_ how you create it. ## Disclaimer of Use Private Messages are **not** encrypted and the Admin team has the ability to access and review them. Users are expected to follow the Code of Content, even in private messages. ### Create Private Message via Profile Menu - Click on your profile picture in the top-right of the screen ![image|368x98](upload://qxsov40IiILlfxTXV43M4eZm9rr.png) - Double-click the envelope icon ![image|122x42](upload://uPmU79eE6f33sFQKMfLlHZV5y39.png) - Click "New Message" on the left-side menu ![image|172x63](upload://jgIWqCmsVenkSB1aXnFWdY80n56.png) ### Create Private Message via the Topic Editor - Click the "+New Topic" button on any screen it is visible ![image|253x54](upload://AfxQO9Re8WuuBRcwwINygqGcCys.png) - Click the `+` button on the upper-left side of the editor window ![image|262x134](upload://tXNbmBec79EHvMXWSS7wj4kWULQ.png) - Click `New message` ![image|253x54](upload://AfxQO9Re8WuuBRcwwINygqGcCys.png) ### Addressing Individuals and Groups **Individuals** Begin typing a user's Discourse name in the `Add user` field. Discourse will populate possible candidates ![image|425x131](upload://i0ee8ZEqJ98nurzh5WmSGgvd4am.png) **Groups** You can message different Discourse groups like `@moderators` or `@admins` ![image|448x170](upload://hyxqR0xI98CYrtZ0MsB9J5wOQvv.png) # Images It is possible to upload images to Discourse; however, the preference is that users will host from a site like imgur. Direct uploads to the Discourse increase our storage footprint, with in turn increases the cost for maintaining the site. Be mindful: if you can host it elsewhere, please do. ## Imgur Thumbnail Guide Append any of these letters to the base filename of an imgur image to automatically scale it down. ``` s = Small Square (90×90) as seen in the example above b = Big Square (160×160) t = Small Thumbnail (160×160) m = Medium Thumbnail (320×320) l = Large Thumbnail (640×640) as seen in the example above h = Huge Thumbnail (1024×1024) ``` For instance, to get the Big Square version of the `![img](https://i.imgur.com/b0abKrx.png)` file, one would rename it to `![img](https://i.imgur.com/b0abKrxb.png)` ![img](https://i.imgur.com/b0abKrxb.png) ## Tagging Images It is possible to tag an image using HTML so that text appears when a user places their mouse cursor over it: ``` ``` -------------------------