diff --git a/source/img/Guide_Custom_CSS.png b/source/img/Guide_Custom_CSS.png index 25e60577..21f74bff 100644 Binary files a/source/img/Guide_Custom_CSS.png and b/source/img/Guide_Custom_CSS.png differ diff --git a/source/img/guides/collapsible.png b/source/img/guides/collapsible.png index 7b7d4386..d6cf0516 100644 Binary files a/source/img/guides/collapsible.png and b/source/img/guides/collapsible.png differ diff --git a/source/img/guides/editnav.png b/source/img/guides/editnav.png index 6e845740..74af1545 100644 Binary files a/source/img/guides/editnav.png and b/source/img/guides/editnav.png differ diff --git a/source/img/guides/editor-ribbon.png b/source/img/guides/editor-ribbon.png index 0a11bd8a..3ae4ecf2 100644 Binary files a/source/img/guides/editor-ribbon.png and b/source/img/guides/editor-ribbon.png differ diff --git a/source/img/guides/inlinemath.png b/source/img/guides/inlinemath.png new file mode 100644 index 00000000..2b1055a0 Binary files /dev/null and b/source/img/guides/inlinemath.png differ diff --git a/source/img/guides/mathjax.png b/source/img/guides/mathjax.png index a94dde1c..865c166f 100644 Binary files a/source/img/guides/mathjax.png and b/source/img/guides/mathjax.png differ diff --git a/source/img/guides/multilinemath.png b/source/img/guides/multilinemath.png new file mode 100644 index 00000000..1cc4c803 Binary files /dev/null and b/source/img/guides/multilinemath.png differ diff --git a/source/instructors/authoring/guides/markdown_content.rst b/source/instructors/authoring/guides/markdown_content.rst index 9294ae33..503c54a4 100644 --- a/source/instructors/authoring/guides/markdown_content.rst +++ b/source/instructors/authoring/guides/markdown_content.rst @@ -3,66 +3,70 @@ .. _markdown-content-editing: -Content editing +Content Editing =============== -Content can be written in +Content can be written in Markdown, a lightweight markup language for adding formatting to plaintext documents. See below for more details. -- **Markdown** - Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. More information below. +**Selecting Sections in Edit Mode** +To select a section while editing: -When you are in edit mode, you can select a section by +- Use the navigation buttons in the header area +- Choose a section from the index list -- using the navigation buttons in the header area -- selecting a section from the index list - - .. image:: /img/guides/editnav.png - :alt: editnav +.. image:: /img/guides/editnav.png + :alt: editnav +Renaming the Section +-------------------- +To rename your section, click on the section title in the header area. -Renaming the Section -******************** -Rename your section by clicking on the section title in the header area. +Writing Content +--------------- -Writing content -*************** Write content in the main content area. -You can also set hotkeys for a range of commonly used editing functions. +**Editing Hotkeys** + +Set hotkeys for commonly used editing functions: - Bold selected text - Enumerate selected text - Order selected text - Make selected text as a code block -- Command button +- Command button -See the **[guides]** area in the :ref:`User Preferences ` +For more information, see the **[guides]** area in :ref:`User Preferences `. Custom CSS -********** +---------- -In Play Mode or as you preview, your content is rendered as students will see it. You can override the default CSS styling by accessing **Tools->Guide->Add Custom CSS** +Your content in Play Mode or preview matches the student view exactly. + +To customize the default CSS styling, navigate to **Tools → Guide → Add Custom CSS**. .. image:: /img/guides/guidecss.png :alt: Guide CSS +To restore the default CSS styling, select **Reset Custom CSS**. -'Reset Custom CSS' will restore the default CSS styling - -Click here for details on how to insert :ref:`images, videos and hyperlinks `. +For instructions on inserting :ref:`images, videos and hyperlinks `, see the media guide. .. _setting_course_level_custom_css: + Setting Course Level Custom CSS --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You can now apply custom CSS at the **course level**, eliminating the need to apply CSS to each assignment individually. This can be configured by adding CSS URLs in the **Course Details** section. To configure this, follow these steps: -1. Click on **Courses** from the left navigation menu. +1. Click on **Courses** from the top navigation menu. 2. Select the course you want to edit. 3. Click **Course Details**. 4. Add the URLs in the following fields: @@ -70,31 +74,38 @@ To configure this, follow these steps: .. image:: /img/Guide_Custom_CSS.png :alt: Guide Custom CSS +.. list-table:: + :widths: 25 75 + :header-rows: 1 -- **Override Guides CSS URL:** - - - This URL completely replaces Codio's default CSS. - - If a URL is provided, Codio’s default CSS will be ignored, and the CSS from the specified URL will be used. + * - CSS Option + - Description + * - **Override Guides CSS URL** + - This URL completely replaces Codio's default CSS. If a URL is provided, Codio's default CSS will be ignored, and the CSS from the specified URL will be used. + * - **Extra Guides CSS URL** + - This URL adds additional CSS on top of Codio's default styles. It enhances or customizes the existing Codio CSS without removing it. -- **Extra Guides CSS URL:** - - - This URL adds additional CSS on top of Codio’s default styles. - - It enhances or customizes the existing Codio CSS without removing it. 5. Click **Save** to apply the changes. + Markdown -******** +-------- -To assist with your creation of markdown content, an editor ribbon is available, including Codio specific buttons to :ref:`open/close content ` within Guides. +An editor ribbon is available to help you create markdown content, including Codio-specific buttons for :ref:`opening and closing content ` within Guides. .. image:: /img/guides/editor-ribbon.png :alt: Markdown Editor Ribbon -If you prefer to write markdown yourself, a summary of formatting codes: +For those who prefer to write markdown manually, here's a summary of formatting codes: + + +Basic Formatting +---------------- Headers/Titles -************** +~~~~~~~~~~~~~~ + To display a header or title, you can use the `#` character at the start of the line. The more `#` characters you add, the smaller the font. .. code:: markdown @@ -106,8 +117,9 @@ To display a header or title, you can use the `#` character at the start of the Bold and Italic -*************** -To create bold or italic text, you use `**` and `*` either side of the respective words. +~~~~~~~~~~~~~~~ + +To create bold or italic text, you use `**` and `*` either side of the text. .. code:: markdown @@ -115,32 +127,50 @@ To create bold or italic text, you use `**` and `*` either side of the respectiv I *really* like chocolate -Bullet Lists -************ -To create a list of bullet points, you start the line with a `-` -.. code:: markdown +Lists +~~~~~ - - Bullet 1 - - Bullet 2 - - Bullet 3 - - etc +.. list-table:: Lists + :header-rows: 1 + :widths: 20 40 40 + * - List Type + - Description + - Syntax + * - Bullet Lists + - To create a list of bullet points, start each line with a ``-`` + - .. code:: markdown -Numbered Lists -************** -To create a numbered list, you start the line with a `1.` The numbers are automatically calculated for you. + - Bullet 1 + - Bullet 2 + - Bullet 3 + - etc + * - Numbered Lists + - To create a numbered list, start each line with ``1.`` The numbers are automatically calculated for you. + - .. code:: markdown -.. code:: markdown + 1. Item 1 + 1. Item 2 + 1. Item 3 + 1. etc + * - Indented Lists + - To indent a list, add 2 spaces before each line. + - .. code:: markdown + + - Bullet 1 + - Bullet 2 + - Bullet 3 + - etc - 1. Item 1 - 1. Item 2 - 1. Item 3 - 1. etc Code Blocks -*********** -If you want to show code in a box with syntax highlighting, surround it with three backticks. For example, the following JavaScript snippet: +----------- + +Code blocks display syntax-highlighted code in a formatted box. To create one, wrap your code between two lines of three backticks. Here is an example using Javascript. + + +This JavaScript code: .. code:: javascript @@ -150,7 +180,7 @@ If you want to show code in a box with syntax highlighting, surround it with thr } -is written with the first line as +is created using: .. code:: markdown @@ -158,27 +188,29 @@ is written with the first line as // your code... ``` -then your code, and the last line as three backticks. +The opening backticks should include a language identifier (e.g., ``js``, ``python``) for proper syntax highlighting. Many languages are supported. See a full list of supported languages `here `_. +Copy to Clipboard Feature +~~~~~~~~~~~~~~~~~~~~~~~~~ -Note that you can specify a language type after the top 3 back ticks. Entering `python` after the backticks would apply syntax highlighting for python. Many languages are supported. See a full list of supported languages `here `_. You should search for your language and then use the `alias` shown. +Code blocks automatically include a 'copy to clipboard' button, allowing students to easily copy code for use in assignments. -The Code block also includes a 'copy to clipboard' button to allow students to easily copy the code to their clipboard where you may want them to run this code in the assignment +.. image:: /img/guides/copyclipboard.png + :alt: copy to clipboard - .. image:: /img/guides/copyclipboard.png - :alt: copy to clipboard - -If you wish to suppress the 'copy to clipboard' button in the code block, append ```-hide-clipboard``` to the first line +If you wish to suppress the 'copy to clipboard' button in the code block, append ```-hide-clipboard``` to the first line. Example - .. image:: /img/guides/hideclipboard.png - :alt: hide copy to clipboard +.. image:: /img/guides/hideclipboard.png + :alt: hide copy to clipboard + Code Segments -************* +------------- + If you want to insert a piece of code inline with the rest of your text, then you use a single \` (backtick) character either side of the text. For example, We can define a variable `var x;` if we like @@ -187,12 +219,17 @@ We can define a variable `var x;` if we like We can define a variable \`var x;\` if we like +.. note:: + For multi-line code or longer snippets, use code blocks instead (see Code Blocks section). + + + .. _math-blocks: Math Blocks -************* +----------- -To add mathematical expressions, you can use the `math` block as follows: +Display mathematical formulas and equations using LaTeX syntax in math blocks. To add mathematical expressions, you can use the `math` block as follows: .. code:: markdown @@ -207,38 +244,21 @@ The example above will render: :width: 60% :align: center -Indented Lists -************** -If you want to indent a list, then indent just 2 spaces and it will indent. +.. important:: + + Math blocks do not include a clipboard icon for copying content. -.. code:: markdown +Callout Blocks +-------------- - - Bullet 1 - - Bullet 2 - - Bullet 3 - - etc +If you want to show a callout block, a number of options are available. +Available callout types: -Callout Blocks -************** -If you want to show a callout block a number of options are available and others can be easily added if required - - - important - - info - - warning - - topic - - definition - - challenge - - guidance - - meetup - - hackathon - - create - - calendar - - growthhack - - xdiscipline - - debugging - -e.g. +``important``, ``info``, ``warning``, ``topic``, ``definition``, ``challenge``, ``guidance``, ``meetup``, ``hackathon``, ``create``, ``calendar``, ``growthhack``, ``xdiscipline``, ``debugging`` + + +For example: .. code:: markdown @@ -249,55 +269,73 @@ e.g. ||| - .. image:: /img/guides/callout_info.png - :alt: calloutinfo +.. image:: /img/guides/callout_info.png + :alt: calloutinfo -The **Guidance** callout block is only visible in play mode to designated teachers within a course. It is not visible for students. +.. note:: The **Guidance** callout block is only visible in play mode to designated teachers within a course. It is not visible for students. Hyperlinks, Images, Videos & iframes -************************************ -We describe these in :ref:`this section `. +------------------------------------ + +For detailed instructions on adding hyperlinks, images, videos, and iframes, see :ref:`Adding Media `. + HTML -**** -You can include HTML tags +---- +Include HTML tags directly in your content for additional formatting and functionality. + Latex / MathJax -*************** +--------------- -Latex is supported using `MathJax `_. For example +Latex is supported using `MathJax `_. + +**Inline Math** + +Use single ``$`` symbols to wrap inline equations: .. code:: markdown - When $a \ne 0$ there are two solutions to $(ax^2 + bx + c = 0)$ and they are $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ + When $a \ne 0$ there are two solutions to $(ax^2 + bx + c = 0)$ + +The example above will render: + +.. image:: /img/guides/inlinemath.png + :alt: MathJax + :width: 450px + +**Multi-line Math** + +Use double ``$$`` symbols for multi-line equations: - and for multiple lines we do the following +.. code:: markdown $$ y=x^2 y=\frac{x^2}{x+1} $$ +The example above will render: + +.. image:: /img/guides/multilinemath.png + :alt: MathJax + :width: 450px -:ref:`Click here ` for more details on Latex and Mathjax. +:ref:`For more information on LaTeX and MathJax `. - .. image:: /img/guides/mathjax.png - :alt: MathJax -Inline math equations are encapsulated in a single `$` like this: $\omega = d\phi / dt$. Collapsible Content -******************* -In writing content, it is sometimes useful to provide information for the student, but to keep it hidden until they are ready. +------------------- -This can be achieved with collapsible content and the `
` elements. The content is treated as HTML and as such a mix of HTML and Markdown can be required. +Collapsible content is useful for providing information that students can reveal when ready. Use the
HTML elements, which may require mixing HTML and Markdown syntax. .. Note:: @@ -308,7 +346,7 @@ This can be achieved with collapsible content and the `
` elem - If you want the content to show by default, use `
`. Example -------- +""""""" .. image:: /img/guides/collapsible.png :alt: Collapsible content @@ -319,7 +357,7 @@ The following is the code used to create the image above. Three code blocks are .. code:: markdown - ###Example Collapsible Content + ## Example Collapsible Content
There are some Special Numeric Values which are part of the number data type. For each of the variables a band c print out their data types and values. @@ -348,3 +386,14 @@ The following is the code used to create the image above. Three code blocks are + + + + + + + + + + +