How to Edit this Website

This post is an introduction on how to edit the website (rave.wiki), which completely runs on Github with no dedicated hosting servers.

To start, you must have a Github account and must apply to be a member of rave-ieeg group.

1. Create a new documentation

If you want to edit an existing page, see 3. Edit an existing page

All the documentation files are stored at directory posts/, which contains several folders that roughly classify the documents.

To add a new documentation page, open https://github.com/rave-ieeg/rave-ieeg.github.io/tree/main/posts. Please select a proper folder for the document, click on “Add File” button (see Figure 1), and click on “Create new file”.

Figure 1: Screenshot of Github buttons to create a new file.
Github will open its online editor. The first thing to do is to give your new baby a good name, which should start with letters (a-z or A-Z) and often end with file extension .md (stands for “Markdown” format).

Figure 2: Create a new file name: avoid special letters especially / in the file name (unless you want to create a folder). Filenames starting with _ will be “hidden” markdown snippets that will not be rendered as a page. However, it can be included in other documents (see Section “[3. Edit markdown files]” below).

After choosing the file name, copy the following meta header into the content box. Make sure you copy the entire header (including “---”). Edit the key information such as title, description, date, author, and categories as they will affect how the page is arranged and displayed in the Documentation page.

---
title: "How to Edit this Website"
description: |
  Editor's notes on how to edit this website
date: 2024-09-01
author: 
  - name: Zhengjia Wang
    affiliations: 
      - name: "Dept. of Neurosurgery, University of Pennsylvania"
categories:
  - "Editor's Notes"
copyright: 
  holder: Beauchamp's Lab
  year: 2024
---

Start a new line after the second dash “---”, and now you can begin editing the content (See Section “[3. Edit markdown files]” below on how to format your content).

2. Save the page

We all have experienced losing unsaved work. To avoid such frustration, it is a good practice to save the page before you regret.

On Github, “saving the work” is called Commit changes. To commit the pages you have just created, simply scroll up to the top of the editor, and you will see the button Commit changes with an outstanding color (green?). Click on this button, please ensure that the commit is made directly to the main branch. You are more than welcome to comment on the changes. For example, “This is my first page!”, “I feel fantastic”, or “The best Philly cheese steak I’ve ever had was in Houston” for back-tracking the website history. However, comment is completely optional.

3. Edit an existing page

To edit an existing page, you need to find the location of the source document. The easiest method is to open the RAVE website and navigate to the page that you want to edit. The content-bar should contain the following options:

Click on “ Edit this page”, and the browser should take you directly to the editor page. Please BE AWARE that if Github asks you to “fork” the project, DON’T do it. Check if you have logged out of the Github. Please make sure you are logged into the Github!

4. Edit markdown files

This website is based on Pandoc and uses its variation of markdown as its underlying document syntax. Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read.

There are many tutorials on how to edit markdown files. The following tutorial comes from quarto documentation. Most of the time you only need to remember the basics such as text formatting, headings, list, links and images.

Here is a list of common types. Pick one to see the format:

Headings

Markdown Syntax	Output
`# Header 1`	Header 1
`## Header 2`	Header 2
`### Header 3`	Header 3
`#### Header 4`	Header 4
`##### Header 5`	Header 5
`###### Header 6`	Header 6

Text ~~Formatting~~

Markdown Syntax	Output
`italics, bold, *bold italics*`	italics, bold, *bold italics*
`superscript^2^ / subscript~2~`	superscript² / subscript₂
`~~strikethrough~~`	~~strikethrough~~
`verbatim code`	`verbatim code`
`> Blockquote`	Blockquote
`::: {.classname} Div :::`	Div
`\| Line Block \| Spaces and newlines \| are preserved`	Line Block Spaces and newlines are preserved
`endash: --`	endash: –
`emdash: ---`	emdash: —

Lists

Markdown Syntax	Output
`* unordered list + sub-item 1 + sub-item 2 - sub-sub-item 1`	unordered list sub-item 1 sub-item 2 sub-sub-item 1
`* item 2 Continued (indent 4 spaces)`	item 2 Continued (indent 4 spaces)
`1. ordered list 2. item 2 i) sub-item 1 A. sub-sub-item 1`	ordered list item 2 sub-item 1 sub-sub-item 1
`- [ ] Task 1 - [x] Task 2`	Task 1 Task 2
`(@) A list whose numbering continues after (@) an interruption`	A list whose numbering continues after an interruption
`::: {} 1. A list ::: ::: {} 1. Followed by another list :::`	A list Followed by another list
`term : definition`	term definition

Note that unlike other Markdown renderers (notably Jupyter and GitHub), lists in rave.wiki require an entire blank line above the list. Otherwise the list will not be rendered in list form, rather it will all appear as normal text along a single line.

Footnotes¹

Pandoc supports numbering and formatting footnotes using the following syntax:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

The above syntax generates the following output:

Here is a footnote reference,² and another.³

This paragraph won’t be part of the note, because it isn’t indented.

In addition, you can also write single paragraph footnotes inline using the following syntax:

Here is an inline note.^[Inlines notes are easier to write,
since you don't have to pick an identifier and move down to
type the note.]

This syntax generates the following output:

Here is an inline note.⁴

The footnotes that are generated from the above examples are included in the Example Footnotes section at the bottom of the page. See the Pandoc Footnotes for additional information.

Media (link, figure, video, …)

Links & Images

If you want to include your own figures, please upload figures from Github. Make sure the figure is at the same directory as the markdown file.

Markdown Syntax	Output
`<https://rave.wiki>` link	https://rave.wiki
`[RAVE Website](https://rave.wiki)` link with different text	RAVE Website
`![Caption](rave-neuroimage.webp)` image	Caption
`![Caption](rave-neuroimage.webp){width="30%"}` image with 30% width	Caption
`[![Caption](rave-neuroimage.webp){width="30%"}](https://rave.wiki)` image with link
`[![Caption](rave-neuroimage.webp "RAVE"){width="30%"}](https://rave.wiki)` image with link and tooltip (hover text)
`[![](missing-image.webp){width="30%" fig-alt="ss"}](https://rave.wiki)` image with link: alt-text when image is missing

Videos

You can include videos in documents using the {{< video >}} shortcode. For example, here we embed a YouTube video:

{{< video https://www.youtube.com/watch?v=hfHZMfqIaGY >}}

Videos can refer to video files (e.g. MPEG) or can be links to videos published on YouTube, Vimeo, or Brightcove. Learn more in the article on Videos.

Tables

Markdown Syntax

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Output

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

Learn more in the article on Tables.

Source Code

Use ``` to delimit blocks of source code:

```
code
```

Add a language to syntax highlight code blocks:

```r
rave::start_rave2()
```

```python
import numpy as np
```

Pandoc supports syntax highlighting for over 140 different languages. If your language is not supported then you can use the default language to get a similar visual treatment:

```default
code
```

$E_{quations}$

Use $ delimiters for inline math and $$ delimiters for display math. For example:

Markdown Syntax Output

Markdown Syntax	Output
`inline math: $E = mc^{2}$`	inline math: \(E=mc^{2}\)
`display math: $$E = mc^{2}$$`	display math: \[E = mc^{2}\]

inline math: $E = mc^{2}$

inline math: $E=mc^{2}$

display math:

$$E = mc^{2}$$

display math:

\[E = mc^{2}\]

Here are some advanced usages:

<HTML code>

Raw content without parsing

Raw content can be included directly without parsing it. A raw block starts with ```{= followed by a format and closing }, e.g. here’s a raw HTML block:

```{=html}
<iframe src="https://rave.wiki/" width="500" height="400"></iframe>
```

Divs and Spans

For HTML <div> and <span> tags, there is a better option. You can add classes, attributes, and other identifiers to regions of content using Divs and Spans. The difference between this type and “raw” content above is that the content inside ::: will be parsed as markdown.

For example, here we add the “border” class to a region of content using a div (:::):

::: {.border}
This content can be styled with a border
:::

Once rendered to HTML, Quarto will translate the markdown into:

<div class="border">
  <p>This content can be styled with a border</p>
</div>

Divs start with a fence containing at least three consecutive colons plus some attributes. The attributes may optionally be followed by another string of consecutive colons. The Div ends with another line containing a string of at least three consecutive colons. The Div should be separated by blank lines from preceding and following blocks. Divs may also be nested. For example

::::: {#special .sidebar}

::: {.warning}
Here is a warning.
:::

More content.
:::::

Once rendered to HTML, Quarto will translate the markdown into:

<div id="special" class="sidebar">
  <div class="warning">
    <p>Here is a warning.</p>
  </div>
  <p>More content.</p>
</div>

Fences without attributes are always closing fences. Unlike with fenced code blocks, the number of colons in the closing fence need not match the number in the opening fence. However, it can be helpful for visual clarity to use fences of different lengths to distinguish nested divs from their parents.

A bracketed sequence of inlines, as one would use to begin a link, will be treated as a Span with attributes if it is followed immediately by attributes:

[This is *some text*]{.class key="val"}

Once rendered to HTML, Quarto will translate the markdown into:

<span class="class" data-key="val">
  This is <em>some text</em>
</span>

Callouts (collapsible content)

Callout

Callouts are an excellent way to draw extra attention to certain concepts, or to more clearly indicate that certain content is supplemental or applicable to only some scenarios.

There are five different types of callouts available.

note
warning
important
tip
caution

The color and icon will be different depending upon the type that you select. Here are what the various types look like in HTML output:

Note

Note that there are five types of callouts, including: note, tip, warning, caution, and important.

Warning

Callouts provide a simple way to attract attention, for example, to this warning.

This is Important

Danger, callouts will really improve your writing.

Tip With Title

This is an example of a callout with a title.

Expand To Learn About Collapse

This is an example of a ‘collapsed’ caution callout that can be expanded by the user. You can use collapse="true" to collapse it by default or collapse="false" to make a collapsible callout that is expanded by default.

Markdown Syntax

Create callouts in markdown using the following syntax (note that the first markdown heading used within the callout is used as the callout heading):

::: {.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::

::: {.callout-tip}
## Tip with Title

This is an example of a callout with a title.
:::

::: {.callout-caution collapse="true"}
## Expand To Learn About Collapse

This is an example of a 'folded' caution callout that can be expanded by the user. You can use `collapse="true"` to collapse it by default or `collapse="false"` to make a collapsible callout that is expanded by default.
:::

Note that above callout titles are defined by using a heading at the top of the callout. If you prefer, you can also specify the title using the title attribute. For example:

::: {.callout-tip title="Tip with Title"}
This is a callout with a title.
:::

Customizing Appearance

Collapse

You can create ‘folded’ callouts that can be expanded by the user by settings the collapse attribute on the callout. If you set collapse=true, the callout will be expandable, but will be collapsed by default. If you set collapse=false, the callout will be expandable, but will be expanded by default.

Appearance

Callouts have 3 different looks you can use.

`default`	The default appearance with colored header and an icon.
`simple`	A lighter weight appearance that doesn’t include a colored header background.
`minimal`	A minimal treatment that applies borders to the callout, but doesn’t include a header background color or icon.

Pop-up dialogue (modal)

Modal is a great way to show dialogues with a catchy button. Here is an example:

::: {.rave-modal data-type="botton" data-class="btn btn-primary" data-label="Click me!" data-title="I am the title!"}

RAVE is a very powerful tool!

:::

Output:

Explanation:

Element class .rave-modal will let this website mark the content as modal content;
data-type="botton" creates a button;
data-label will become the button label;
data-title is the title of pop-up dialogue;
data-class="btn btn-primary" styles the button with solid primary background. Common styles are:
- Normal
  
  data-class=“btn btn-primary” data-class=“btn btn-secondary” data-class=“btn btn-success” data-class=“btn btn-danger” data-class=“btn btn-warning” data-class=“btn btn-info” data-class=“btn btn-light” data-class=“btn btn-dark”
- Outlined
  
  data-class=“btn btn-outline-primary” data-class=“btn btn-outline-secondary” data-class=“btn btn-outline-success” data-class=“btn btn-outline-danger” data-class=“btn btn-outline-warning” data-class=“btn btn-outline-info” data-class=“btn btn-outline-light” data-class=“btn btn-outline-dark”
- Size
  
  data-class=“btn btn-lg btn-primary” data-class=“btn btn-sm btn-primary”

Here is an example of customization:

* ::: {.rave-modal data-type="span" data-class="text-decoration-underline" data-label="Click this link to show the message!" data-title="Hello World!"}
  RAVE is a very powerful tool!
  :::
* ::: {.rave-modal data-type="span" data-class="text-decoration-underline" data-label="How about this one?" data-title="Hello Again!"}
  RAVE is indeed a very powerful tool!
  :::

Output:

RAVE is a very powerful tool!
RAVE is indeed a very powerful tool!

Document {snippets}

When a document is too long, it is a good practice to break it down into several small snippets.

For example, the main source of this document how-to-edit-this-website.md only has around 200 lines. Most of the formatting details are separated out into small snippets.

To create a snippet, simply create a markdown document whose name starts with an underscore _. For example _markdown-advanced-snippet.md is the file name of text you are reading. Each document snippet is just a normal markdown file. They can be independently edited.

To include the snippet into the main document, you can use the following markdown:

{{< include _markdown-advanced-snippet.md >}}

Document snippets work well with callouts and pop-up modals.

Here’s an example using callouts

::: {.callout collapse="true" appearance="simple"}
### Document `{`snippets`}` 

{{< include _markdown-advanced-snippet.md >}}
:::

This is an example using pop-up modal

::: {.rave-modal data-type="botton" data-class="btn btn-primary" data-label="MacOS" data-title="Prerequisite on MacOS"}
{{< include _prerequisite_macos.md >}}
:::

5. View the results

5.1 Preview during the editing

Github online editor provides a decent tool for previewing the results before publishing changes. This feature allows you to test different formatting ideas before saving changes. To preview the page, scroll up to the top of the editor and click on the Preview button right next to Edit. The markdown pre-render results will show up. To continue editing the pages, click on Edit button and the viewer will switch back.

“Edit” mode	“Preview” mode

5.2 View the final results

When you commit (save) the changes to the Github main repository branch, an Github bot will be invoked to render the whole website. This process is completely automatic and normally requires no manual intervention. Here is the link if you would like to track the progress out of curiosity: https://github.com/rave-ieeg/rave-ieeg.github.io/actions. The rendering process usually costs several minutes before the updates are deployed to RAVE website.

Screenshot of RAVE website automatic building process.

Example Footnotes

Here is the footnote.↩︎
Here is the footnote.↩︎
Here’s one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.
```
{ some.code }
```
The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.↩︎
Inlines notes are easier to write, since you don’t have to pick an identifier and move down to type the note.↩︎

Reuse

CC BY 4.0

1. Create a new documentation

2. Save the page

3. Edit an existing page

4. Edit markdown files

Header 1

Header 2

Header 3

Header 4

Header 5

Header 6

Links & Images

Videos

Markdown Syntax

Output

Raw content without parsing

Divs and Spans

Callout

Markdown Syntax

Customizing Appearance

Collapse

Appearance

5. View the results

5.1 Preview during the editing

5.2 View the final results

Example Footnotes

Reuse