From 55aa711ef9f15c14c82311705e4087c73d191f31 Mon Sep 17 00:00:00 2001 From: Nathan Wang Date: Mon, 22 Jun 2020 13:58:36 -0700 Subject: [PATCH] update docs --- Content Documentation.md | 123 +++++++---------------------------- content/1_Intro/Languages.md | 2 +- gatsby-browser.tsx | 10 --- src/components/Markdown.tsx | 4 +- 4 files changed, 28 insertions(+), 111 deletions(-) diff --git a/Content Documentation.md b/Content Documentation.md index d54b615..f0fe482 100644 --- a/Content Documentation.md +++ b/Content Documentation.md @@ -1,5 +1,3 @@ -// WIP need to update this - ## Content Formatting Documentation All modules are written in [Markdown](https://www.markdownguide.org/cheat-sheet/). There are special additions to the markdown that we have added to this site. @@ -8,9 +6,9 @@ If you are confused about something, or if there's a certain feature that you wa You can use [StackEdit](https://stackedit.io/) to check that latex renders properly. -### `ordering.js` +### `ordering.ts` -Located at `content/ordering.js`, this file stores the ordering of the modules. Hopefully the format is self-explanatory +Located at `content/ordering.ts`, this file stores the ordering of the modules. Hopefully the format is self-explanatory (it matches based on "slug"). Let Nathan Wang know if you have questions. ### Frontmatter @@ -18,116 +16,62 @@ Located at `content/ordering.js`, this file stores the ordering of the modules. [Frontmatter](https://jekyllrb.com/docs/front-matter/) is the stuff in the beginning of each module that's surrounded by three dashes. Frontmatter is written in [YAML](https://yaml.org/). It stores the "metadata" for each module. -YAML formatting is _extremely strict_. Be careful about spaces. +YAML formatting is _extremely strict_. Be careful about spaces. Additionally, escape special characters by wrapping the string with double quotes. - **ID**: _Required_. The ID of the module. Ex: `getting-started`, or `containers`. This ID is used to identify the module, so make sure it is **unique** and **all lowercase with dashes only**. The URL will be generated based off this. - **Title**: _Required_. The title of the module. Ex: `Getting Started` - **Author**: _Required_. The author of the module. Ex: `Unknown` -- **Prerequisites**: _Optional_. Any prerequisites for this module. - -The prerequisite formatting is rather unintuitive. It expects an array of arrays, where the first item is -the name of the prerequisite, and the optional second item is a link. **Note the number of spaces!** - -Example: - -``` -prerequisites: - - - - Prerequisite Name - - https://dummy.prerequisite.link.com/ - - - - Another Prerequisite Without a Link -``` - +- **Description**: _Required_. A short description of the module, similar to what [codecademy](https://www.codecademy.com/learn/paths/computer-science) has in their syllabus. Markdown/Latex does not work in the description field. +- **Prerequisites**: _Optional_. Any prerequisites for this module. (Coming soon: If you want to reference a module as a prerequisite, you can list the module ID.) - **Problems**: _Optional_. A list of problems in the article. As we haven't figured out what we're going to do with **it's best to not include this yet.** For USACO problems, enter each problem as `division_filename`. Ex: `bronze_promote`. -### Module Description - -Everything contained in `module-excerpt` tags is part of the "module description." It gets rendered on the homepage. Be careful not to use headers -as they will look really weird on the homepage. The module description is also included in the article itself. - -If you don't want a description for the module, just put the `END DESCRIPTION` line as the first line -after the frontmatter. - -If you want a description that appears only on the homepage but not the article, wrap it in -an HTML element with the class `syllabus-only`. Note that you can't use markdown in HTML elements. - -Example: - -``` - - - - - -``` - -This will render as a list in the homepage, but won't appear in the article. - ### Spoilers Spoilers are collapsible elements that only show themselves when the user clicks on it. It's useful -when writing solutions to problems. The styling of the spoilers is still a work in progress (especially for spoilers in lists). - -// TODO update spoiler docs to reflect new tag +when writing solutions to problems. ``` - - Insert OP benq solution here - +- Insert OP benq solution here + + ``` -The `summary` tag is shown. Everything below it is only shown after the user chooses to "reveal" spoilers. - -The formatting of the details is **very delicate**. In particular, note the empty line after the summary tag -and before the content of the details tag. **This empty line must be indented to the beginning of the details tag.** -For example: +### Info Block ``` -- Here's a list -- And below is a details tag in a list (which looks kind of ugly right now; hopefully it'll be fixed soon) --
// Indented with two characters (a dash and a space) - Show Solution // Indented with FOUR spaces - // Indented with TWO spaces - - Insert OP benq solution here // Indented with FOUR spaces -
+ + +**Markdown is Supported!!** + + ``` -### Custom Blocks - -Currently, we only have one custom block (info), but others can easily be added (ex: warning, danger, error, success?). -Just let Nathan Wang know. - -#### Info Block +### Optional Block ``` -[[info | Insert Title Here]] -| Insert Content Here -| **Markdown is Supported!!** + + +Fun fact: the title attribute is optional. + + ``` ### Example Module ``` --- -id: /intro/getting-started +id: getting-started title: Getting Started +description: Welcome to the guide! We'll introduce what programming competitions are and how this guide is organized. author: Nathan Wang order: 1 prerequisites: - - - - Dummy prerequisite - - https://dummy.prerequisite.link.com/ - - - - Another Prerequisite + - Dummy prerequisite + - running-cpp problems: - bronze_promote - bronze_word @@ -135,22 +79,5 @@ problems: - bronze_square --- - - - - - - -
- Show Solution - - - Insert OP benq solution here -
- # Hello World! ``` diff --git a/content/1_Intro/Languages.md b/content/1_Intro/Languages.md index e7346a6..a8d858e 100644 --- a/content/1_Intro/Languages.md +++ b/content/1_Intro/Languages.md @@ -2,7 +2,7 @@ id: lang title: Languages author: Nathan Wang, Benjamin Qi -description: "What languages you can use for programming contests and what you're expected to know before continuing." +description: What languages you can use for programming contests and what you're expected to know before continuing. --- ## Choosing a Language diff --git a/gatsby-browser.tsx b/gatsby-browser.tsx index 68fc8c2..0a45175 100644 --- a/gatsby-browser.tsx +++ b/gatsby-browser.tsx @@ -47,16 +47,6 @@ const SpoilerComponent = ({ children, title }) => { }; const components = { - wrapper: ({ excerptOnly = false, children }) => { - if (excerptOnly) { - for (let child of children) { - if (child.props.originalType === 'module-excerpt') return child; - } - return null; - } - - return children; - }, 'module-excerpt': props =>
, spoiler: SpoilerComponent, 'info-block': ({ diff --git a/src/components/Markdown.tsx b/src/components/Markdown.tsx index 11de400..3159580 100644 --- a/src/components/Markdown.tsx +++ b/src/components/Markdown.tsx @@ -5,10 +5,10 @@ import 'katex/dist/katex.min.css'; import '../styles/prism-theme.css'; import { MDXRenderer } from 'gatsby-plugin-mdx'; -const Markdown = ({ body, className, excerptOnly = false }) => { +const Markdown = ({ body, className }) => { return (
- {body} + {body}
); };