Markdown and HTML working together, good idea?

HTML and qmd

HTML

qmd

quarto

HTML and qmd discussion

Author

albertprofe

Published

Tuesday, June 1, 2021

Modified

Friday, November 1, 2024

1 Introduction

📘 Markdown and HTML

Overall, it is generally best to avoid mixing HTML and Markdown in the same document, unless you are confident that you can do so without introducing errors or inconsistencies.

Instead, it is often better to use one language exclusively, and to use the appropriate syntax and formatting for that language

2 Problems

Display: If the HTML and Markdown are not properly formatted or nested, the resulting document may not be readable or display correctly. This can lead to confusion for readers and make the document difficult to understand.
Maintain: Mixing HTML and Markdown can make it difficult to maintain the document, as changes to one language may affect the other. This can result in errors and inconsistencies, and make it more challenging to update the document over time.
Incompatibilities: Different Markdown parsers and HTML renderers may have different interpretations of the mixed language, leading to differences in how the document is displayed or interpreted. This can cause confusion for readers and make it difficult to ensure that the document is consistently displayed across different platforms.

3 Example: creating navigation TABs

3.1 Approach #1: MD + CSS

Publishing website by Quarto engine

3.2 Before

Students will need to have a basic understanding of web development, including HTML, CSS, and JavaScript.

3.3 Goal

In this project, students will be required to create a web application using HTML, CSS, and JavaScript. They will also need to understand and use Markdown to format their project’s documentation. Additionally, they will need to use GitHub and Visual Code to manage their project’s code and collaborate with their peers.

3.4 Tasks

In the first part of the project, students will create a basic web page using markdown and publish it on Github repository using Visual Code. This will involve creating a new repository on Github and learning how to use markdown to format text and create links.

In the second part of the project, students will learn how to publish their website on gh-pages, a service provided by Github for hosting static websites. This will involve learning how to use the gh-pages service and how to deploy their website to the internet.

3.5 Optional

As an optional study, students may also want to learn about using callouts in their markdown documentation. The following links provide useful information on the topic:

markdown-callouts

Callout Blocks Quarto

Getting Started with RDMD

Divs and spans

codepen.io HTML+CSS

Using callouts, links, tabs and CSS can help to improve the readability and organization of a markdown document, making it easier for readers to understand and navigate the content.

To take their project to the next level, students may also choose to connect to an API (Application Programming Interface) to retrieve data and render charts using JavaScript. This will require an understanding of how to make HTTP requests and how to manipulate data in JavaScript.

Quarto data sources

3.6 After

The Quarto website project is a great opportunity for students to develop their skills in web development, markdown, and version control using GitHub and Visual Code.

Markdown callouts with calls to CSS classes

::: {.callout-info icon=false  collapse="false"}
## Publishing website by Quarto engine

::: {.tab-nav}
[Before](#before){.tab-link}

[Goal](#goal){.tab-link}

[Tasks](#tasks){.tab-link}

[After](#after){.tab-link}

[Optional](#optional){.tab-link}
:::
::: {.tab-content #before}
### Before
>Students will need to have a **basic understanding of web development**, including HTML, CSS, and JavaScript.

::: {.tab-nav}
[Before](#before){.tab-link}

[Goal](#goal){.tab-link}

[Tasks](#tasks){.tab-link}

[After](#after){.tab-link}

[Optional](#optional){.tab-link}
:::
:::

::: {.tab-content #goal}
### Goal
>In this project, students will be required to create a **web application using HTML, CSS, and JavaScript**. They will also need to understand and use **Markdown to format their project's documentation**. Additionally, they will need to use GitHub and Visual Code to manage their project's code and collaborate with their peers.

::: {.tab-nav}
[Before](#before){.tab-link}

[Goal](#goal){.tab-link}

[Tasks](#tasks){.tab-link}

[After](#after){.tab-link}

[Optional](#optional){.tab-link}
:::
:::

::: {.tab-content #tasks}
### Tasks
>In the first part of the project, students will create a **basic web page using markdown and publish it on Github repository** using Visual Code. This will involve creating a new repository on Github and learning how to use markdown to format text and create links.
>
>In the second part of the project, students will learn how to **publish their website on gh-pages**, a service provided by Github for hosting static websites. This will involve learning how to use the gh-pages service and how to deploy their website to the internet.

::: {.tab-nav}
[Before](#before){.tab-link}

[Goal](#goal){.tab-link}

[Tasks](#tasks){.tab-link}

[After](#after){.tab-link}

[Optional](#optional){.tab-link}
:::
:::

::: {.tab-content #optional}
### Optional
>As an optional study, students may also want to learn about using **callouts in their markdown documentation**. The following links provide useful information on the topic:
>
>- [markdown-callouts](https://oprypin.github.io/markdown-callouts/)
>- [Callout Blocks Quarto](https://quarto.org/docs/authoring/callouts.html)
>- [Getting Started with RDMD](https://rdmd.readme.io/docs/getting-started)
>- [Divs and spans](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans)
>- [codepen.io HTML+CSS](https://codepen.io/dongmikim/pen/VwLqyjQ)
>
>Using **callouts, links, tabs and CSS** can help to improve the readability and organization of a markdown document, making it easier for readers to understand and navigate the content.
>
>To take their project to the next level, students may also choose to connect to an **API** (Application Programming Interface) to **retrieve data and render charts using JavaScript**. This will require an understanding of how to make HTTP requests and how to manipulate data in JavaScript.
>
> - [Quarto data sources](/markup/markupquartoprogramming.qmd)

::: {.tab-nav}
[Before](#before){.tab-link}

[Goal](#goal){.tab-link}

[Tasks](#tasks){.tab-link}

[After](#after){.tab-link}

[Optional](#optional){.tab-link}
:::
:::

::: {.tab-content #after}
### After
>The Quarto website project is a great opportunity for students to develop their skills in **web development, markdown, and version control using GitHub and Visual Code**.

::: {.tab-nav}
[Before](#before){.tab-link}

[Goal](#goal){.tab-link}

[Tasks](#tasks){.tab-link}

[After](#after){.tab-link}

[Optional](#optional){.tab-link}
:::
:::

:::

3.7 Approach #2: HTML + CSS

Create and publish by Quarto

3.8 Approach #3: HTML + CSS + JS

From w3.css: W3.CSS Navigation Tabs

Maven/Gradle Person and Account stored in JSON

<script>
function openLab(evt, labStep) {
  var i, tabcontent, tablinks;
  tabcontent = document.getElementsByClassName("tabcontentw3");
  for (i = 0; i < tabcontent.length; i++) {
    tabcontent[i].style.display = "none";
  }
  tablinks = document.getElementsByClassName("tablinks");
  for (i = 0; i < tablinks.length; i++) {
    tablinks[i].className = tablinks[i].className.replace(" active", "");
  }
  document.getElementById(labStep).style.display = "block";
  evt.currentTarget.className += " active";
}
</script>

3.9 Approach #4: import MDReadme?

Code Blocks

Syntax

We offer both classic single code blocks, as well as a tabbed interface for displaying multiple code blocks concisely! These are written nearly identically to a series of vanilla markdown code snippets, except for their distinct lack of an additional line break separating each subsequent block:

javascript I'm A tab
console.log('Code Tab A');

javascript I'm tab B
console.log('Code Tab B');

Custom CSS

.markdown-body {
  --md-code-background: #e3dcef;
  --md-code-text: #4a2b7b;
  --md-code-tabs: #c6b8dd;
  --md-code-radius: 4px;
}

How to import that feature Navigate by Tabs into Quarto?

This could work but it has been NOT tested:

You could convert Readme Markdown to Quarto Markdown, using a tool like Markdown Converter (https://markdown.pioul.fr/), which supports both flavors of Markdown.
Or Markdowon Parser form Flexmark Java library

In any case, they are not Extensions within Quarto … so, for now, there is NOT an easy and direct solution to do this conversion.

3.10 Approach #5: using Revealjs Quarto

Tabsets Revealjs Quarto

Create a tabset via a markdown div with the class name panel-tabset (e.g. ::: {.panel-tabset}).

::: {.panel-tabset group="language"}
## R

Tab content for R language code and stuff

## Python

Tab content for Python language code and stuff
:::

Each top-level heading within the div creates a new tab. For example, here is the markdown used to implement the first two tabs displayed above:

R
Python

fizz_buzz <- function(fbnums = 1:50) {
  output <- dplyr::case_when(
    fbnums %% 15 == 0 ~ "FizzBuzz",
    fbnums %% 3 == 0 ~ "Fizz",
    fbnums %% 5 == 0 ~ "Buzz",
    TRUE ~ as.character(fbnums)
  )
  print(output)
}

def fizz_buzz(num):
  if num % 15 == 0:
    print("FizzBuzz")
  elif num % 5 == 0:
    print("Buzz")
  elif num % 3 == 0:
    print("Fizz")
  else:
    print(num)

it seems the render does not work properly, it does not show content .. :-(