Verified Commit a64faaa6 authored by exprez135's avatar exprez135

Documentation v1.0 and home page v0.1

parent d1de8928
......@@ -7,9 +7,9 @@ tableOfContents: false
Welcome to CultureBridge Tulsa!
CultureBridge Tulsa is a program of [Cohort XI](Cohort_XI "wikilink") -
CultureBridge Tulsa is a program of Cohort XI –
[Youth Philanthropy
Initiative](Youth_Philanthropy_Initiative "wikilink") in Tulsa,
Initiative](/info/youth-philanthropy-initiative) in Tulsa,
Oklahoma. Welcome to our Manual! This site will give you all of the
information and resources you need to explore CultureBridge, replicate
the program, and run your own immigration simulation!
......@@ -29,7 +29,7 @@ United States of America. As our team of 28 students came together, we
recognized a lack of empathy for the immigrant experience amongst
non-immigrant communities. How could we bridge this gap of
understanding? After collaborating with the [New Tulsans
Initiative](New_Tulsans_Initiative "wikilink"), communicating with
Initiative](/info/new-tulsans-initiative), communicating with
community organizations, and researching best practices, we created the
CultureBridge Immigrant Simulation. By taking on the role of an
immigrant in contemporary America, participants have the opportunity to
......@@ -42,9 +42,9 @@ Explore the Contents section below. Try reading our [Executive
Summary](Executive_Summary "wikilink") and [PR
Packet](PR_Packet "wikilink") to get an idea of who we are. Visit our
website at <https://culturebridgetulsa.com> to see our
[Video](Video "wikilink").
[Video](/supplements/video).
Then, jump into the manual itself. We split the manual into
[Modules](Modules "wikilink") (sections of the simulation itself) and
[Supplements](Supplements "wikilink") (additional materials like the [PR
Packet](PR_Packet "wikilink") or the [Stories](Stories "wikilink")).
[Modules](/modules) (sections of the simulation itself) and
[Supplements](/supplements) (additional materials like the [PR
Packet](PR_Packet "wikilink") or the [Stories](/supplements/stories)).
......@@ -55,7 +55,7 @@ We could also use `culturebridgetulsa.com` if we wanted to replace our other sit
### the layout
{{< tabs "uniqueid" >}}
{{< tabs "mobile-desktop" >}}
{{< tab "Mobile" >}}
## Mobile Layout
......@@ -81,9 +81,10 @@ That's all pretty standard. The other menu (found on the top right) is the speci
{{< /hint >}}
That's about it for the layout! In case you are wondering, these are the fonts we are using:
- Charter for text (this is that font),
- `Fira Mono` for code, and
- ##### Fira Sans for menus & headers.
- Charter for normal text (this is that font),
- `Fira Mono for code, and`
- ##### Fira Sans for menus, headers, and special call-outs
{{< /tab >}}
{{< tab "Desktop" >}}
## Desktop Layout
......@@ -138,7 +139,7 @@ Next, you should see something a little like this:
On the left are the three sections open for you to edit (i.e. Modules, Supplements, and Info). Clicking on these will show you the pages within that. The page which is named after the Section (e.g. Modules in the Module section) is the "home" page for that section.
**Now**, let's take you through a small tour. Click on "Debrief". After a few seconds of loading, you should see something like this:
**Now**, let's take you on a small tour. Click on "Debrief". After a few seconds of loading, you should see something like this:
![First page of Module Debrief](/images/module-page-one.png)
......@@ -158,7 +159,7 @@ Scroll down to the bottom of the page until you see something like this:
Let's go through each of these settings:
1. Flatten Section in TOC: makes this page one of the left-most pages in the Menu (you probably won't use this),
1. Flatten Section in TOC: makes this page one of the left-most pages in the Menu (you probably won't use this).
2. Table of Contents: enables or disables the TOC. If it's a simple page without many headers, disable it. Otherwise, enable it.
3. Hidden: when toggled, hides the page from the Menu.
4. Collapse section: collapses sub-pages, like the Activities and Stories section.
......@@ -190,7 +191,9 @@ Shows the Editorial Workflow described above.
### images and files
You can embed images in your posts using the Rich Text editor. Your files will be uploaded to the server.
You can embed images in your posts using the Rich Text editor. Your files will be uploaded to the server. The "Media" tab shows you everything uploaded thus far.
**Coming soon:** the ability to add files as attachments to pages. This will be helpful for attaching specific copies of certain information (e.g. on a Story page, we can include a PDF of the story that is properly formatted for printing, laminating, and cutting).
### limitations
......@@ -198,11 +201,301 @@ You can embed images in your posts using the Rich Text editor. Your files will b
**Important!** Only have **one** person edit a page at a time.
{{< /hint >}}
### contact me
Have questions? Just contact me!
## markdown
There are some awesome guides on the internet. Here is a great one:
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
Markdown is the source content of every page on our site. When you write in the Rich Text editor, it is writing markdown in the background. Markdown is then taken by our system (see [Hugo](#hugo) below) and formatted into HTML with the templates and CSS we take from our site theme and custom code I've written.
{{< expand "By the way…" >}}
I use markdown for just about everything. I run five or six sites which use the same system as this one. I write my notes in markdown with [Joplin](https://joplinapp.org). Many websites and forums support markdown for writing comments (e.g. Reddit). There are even programs that let you use markdown to write emails (though I **highly** encourage you to [useplaintext.email](https://useplaintext.email)). To read about the original (and somewhat simpler) markdown – and it's philosophy – click [here](https://daringfireball.net/projects/markdown/).
{{< /expand >}}
### rich text vs. markdown on netlify
Most of everything you need can be written in the Rich Text editor. But there are some exceptions. When you want to use these awesome features, you need to change over to markdown mode.
#### supported features in the rich text editor
- Bold & Italics
- Headers (H1 to H6)
- Links
- Quotes
- Unordered lists (i.e. bullet points)
- Ordered lists (i.e. numbered points)
- Images
- Code (in-line)
- Code (block)
#### features which require markdown
##### tables
Tables might be needed. Here is an example:
```markdown
| **Head box** | Content here |
| --- | --- |
| Name | Nate Ijams |
| Age | 18 |
| Coolness level | 1000 |
| Nickname | *The Great* |
| Website | [ijams.tk](https://ijams.tk) |
```
| **Head box** | Content here |
| --- | --- |
| Name | Nate Ijams |
| Age | 18 |
| Coolness level | 1000 |
| Nickname | *The Great* |
| Website | [ijams.tk](https://ijams.tk) |
##### horizontal lines
Lines might be needed to split up content! A haiku split:
```markdown
The west wind whispered,
---
And touched the eyelids of spring:
***
Her eyes, Primroses.
___
```
The west wind whispered,
---
And touched the eyelids of spring:
***
Her eyes, Primroses.
___
Remember, with all markdown content, it's important that you put an empty line between things. You can use `***` or `___` or `---`. All of them work!
##### footnotes
```markdown
This is important information[^1].
This is also important, but it is second[^2].
```
This is important information[^1].
This is also important, but it is second[^2].
But note, at the *bottom* of your page, you need to add something like this:
```markdown
[^1]: Here is a disclaimer about some complication.
[^2]: Here is a reference: google.com.
```
A line will automatically be inserted before the footnotes section.
##### hints
You make it like this:
```tpl
{{</* hint "info" */>}}
**This is a hint**, which is highlighted beautifully.
You can make it blue with "info", yellow with "warning",
and red with "danger".
{{</* /hint */>}}
```
{{< hint info >}}
**This is a hint** which is highlighted beautifully.
You can make it blue with "info", yellow with "warning",
and red with "danger".
{{< /hint >}}
{{< hint warning >}}
**This is a hint** which is highlighted beautifully.
You can make it blue with "info", yellow with "warning",
and red with "danger".
{{< /hint >}}
{{< hint danger >}}
**This is a hint** which is highlighted beautifully.
You can make it blue with "info", yellow with "warning",
and red with "danger".
{{< /hint >}}
##### buttons
{{< button relref="/" >}}Go Home{{< /button >}}
{{< button href="https://lmgtfy.com/?q=puppies&t=i" >}}Be Happy{{< /button >}}
## Markdown
```tpl
{{</* button relref="/" */>}}Go Home{{</* /button */>}}
{{</* button href="https://lmgtfy.com/?q=puppies&t=i" */>}}Be Happy{{</* /button */>}}
```
##### columns
{{< columns >}} <!-- begin columns block -->
# Japanese
初しぐれ猿も小蓑をほしげ也
はつしぐれさるもこみのをほしげなり
<---> <!-- magic sparator, between columns -->
# English
the first cold shower
even the monkey seems to want
a little coat of straw
{{< /columns >}}
```tpl
{{</* columns */>}} <!-- begin columns block -->
# Japanese
初しぐれ猿も小蓑をほしげ也
はつしぐれさるもこみのをほしげなり
<---> <!-- magic sparator, between columns -->
# English
the first cold shower
even the monkey seems to want
a little coat of straw
{{</* /columns */>}}
```
##### expand
{{< expand "don't click here">}}
GOSH DANG. I SAID **DON'T**.
{{< /expand >}}
```tpl
{{</* expand "don't click here" */>}}
GOSH DANG. I SAID **DON'T**.
{{</* /expand */>}}
```
##### katex
{{< katex "[display]" "[class="text-center"]" >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}
```tpl
{{</* katex "[display]" "[class="text-center"]" */>}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{</* /katex */>}}
```
##### tabs
{{< tabs "people" >}}
{{< tab "Non-People" >}}
## Puppies
They are cute. You probably aren't.
{{< /tab >}}
{{< tab "Dumb People" >}}
## Honesty has rewards
I am really proud of you for clicking on this tab. Honesty has many rewards. Most of all, be honest with *yourself*.
{{< /tab >}}
{{< tab "Smart People" >}}
## Ego is bad
Wow. Just wow. Get over yourself.
{{< /tab >}}
{{< /tabs >}}
```tpl
{{</* tabs "people" */>}}
{{</* tab "Non-People" */>}}
## Puppies
They are cute. You probably aren't.
{{</* /tab */>}}
{{</* tab "Dumb People" */>}}
## Honesty has rewards
I am really proud of you for clicking on this tab. Honesty has many rewards. Most of all, be honest with *yourself*.
{{</* /tab */>}}
{{</* tab "Smart People" */>}}
## Ego is bad
Wow. Just wow. Get over yourself.
{{</* /tab */>}}
{{</* /tabs */>}}
```
Where I put `people` in the `{{</* tabs "people" */>}}` above, you need to put a unique id. For example, you can't have two Tab things on one page which both have the ID "people". One might be "people" and the other "manual-explanation".
### must I use markdown?
Maybe not! And you certainly aren't required to put all these fancy things (tabs, hints, columns, buttons). But you probably will need to use tables, footnotes, and horizontal lines at some point.
## Netlify (not the CMS)
[Netlify](https://netlify.com) is the service we are using for hosting, site deployment, and more. This is separate (but related to Netlify CMS). It allows us to build the site automatically when changes are pushed to our Git repository. See the [git section](#git).
## Hugo
[Hugo](https://gohugo.io) is the wonderful static site generator that we are using. In essence, this is how it all works:
1. We write content (in the end, this is in markdown).
2. We gather/create templates: these are written in HTML, CSS, and Go.
3. Hugo takes the content we have and essentially puts everything together with the templates. In the end, it outputs a static site. That is, a folder which contains everything that the website contains, from a home page (index.html) to each photo. You could browse this on your computer, or have a web server serve the files to visitors. This is in contrast to a dynamic site which generates the content then sends it to your computer every time you visit the page.
Hugo is well-know, well-supported, and extensible. I use it for my [school newspaper site](https://thetaliaferrotimes.org), my [personal site](https://ijams.tk), my school's [tutoring site](https://findhelp.ga), and [event sites](https://worldinabox.ga).
## git
[Git](https://git-scm.com/) is a version control system. It is used widely in the development/programming world. It (or other SCM software like Mercurial) is used literally everywhere. It's just one of those essential tools you have to learn. This site is tracked and held in a Git repository. See it at https://gitlab.com/exprez135/culturebridge-hugo/. This can be used to develop new features, keep track of the project history, restore to a previous version, etc. Too many features to count. Resources:
[The Git Book](https://git-scm.com/book/en/v2).
[Resources to learn Git](https://try.github.io/).
[git – the simple guide](https://rogerdudler.github.io/git-guide/).
If you want, you can make a GitLab account and directly clone and work with the repository. Or, just check it out to read the source code. Notice that the end of each page has "Edit this page". That will take you to a direct online editor in the repository, but you'll have to be signed in to use it!
[^1]: Here is a disclaimer about some complication.
[^2]: Here is a reference: google.com.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment