Integration with GitHub
In technical environments, writing documentation and user guides relies heavily on the Markdown format. This practice has become a standard in modern professional workflows.
On GitHub, the majority of projects use the README.md file to provide basic documentation, a quick start guide, or a project overview. The Markdown is interpreted by a parser integrated into GitHub, which generates a readable HTML page accessible to users. This simple and effective approach is now a standard for all projects hosted on the platform.
Limitations and Evolution
However, user needs have evolved. It is now common to want to produce more visually rich content while maintaining added technical or editorial value. It is in this context that GitHub Pages emerged as a complementary solution, enabling the creation of static websites with smooth navigation and a simplified architecture.
Using Super Markdown
Super Markdown addresses these new needs by offering GitHub users an additional presentation layer. It allows you to transform standard Markdown documents into professional, modern, and aesthetically pleasing content, thanks to its system based on Markdown components and an intuitive syntax for regular Markdown users.
How to Use the Super Markdown Integration ?
Two approaches are possible:
- Converting an existing Markdown document: You can keep your current Markdown files and adapt them to the Super Markdown syntax.
- Native creation: You can directly write documents using Super Markdown syntax.
Here is a YAML workflow template to integrate into your repository:
name: Deploy Super Markdown Github Pages
on:
push:
branches:
- master
paths:
- 'docs/**'
workflow_dispatch: {}
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Create output directory
run: mkdir -p _site
- name: Process Markdown files via Super Markdown API
env:
SAAS_AUTH: ${{ secrets.SAAS_APP_AUTH }}
API_URL: "https://super-markdown.com/api/space/public/convert-markdown-file-html/"
REPO_PATH: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
FOLDER_NAME: "github_pages_demo"
MODE: "light-mode"
run: |
for file in docs/*.md; do
filename=$(basename "$file" .md)
echo "--- Processus : $file ---"
# 1. Read the file content
RAW_CONTENT=$(cat "$file")
STEP1=$(echo "$RAW_CONTENT" | sed -E "s|(\[[^]]*\]\()([^)]*)\.md\)|\1${REPO_PATH}/\2.html\)|g")
STEP2=$(echo "$STEP1" | sed -E "s|href=\"([^\"]*)\.md\"|href=\"${REPO_PATH}/\1.html\"|g")
STEP3=$(echo "$STEP2" | sed -E "s|url=\"([^\"]*)\.md\"|url=\"${REPO_PATH}/\1.html\"|g")
# 2. Create JSON payload
# Fields : name_file, folder, convert (bool), data (string)
JSON_PAYLOAD=$(jq -n \
--arg nf "$filename" \
--arg fd "$FOLDER_NAME" \
--arg mode "$MODE" \
--arg dt "$STEP3" \
'{filename: $nf, parent: $fd, convert: false, data: $dt, mode: $mode}')
# 3. Call the API
RESPONSE=$(curl -s -X POST "$API_URL" \
-H "app_auth: $SAAS_AUTH" \
-H "Content-Type: application/json" \
-d "$JSON_PAYLOAD")
echo "Response from API : $RESPONSE"
# 4. Extract the HTML Code
HTML_CODE=$(echo "$RESPONSE" | jq -r '.data.html // empty')
if [ -z "$HTML_CODE" ] || [ "$HTML_CODE" = "null" ]; then
echo "❌ ERROR : HTML not found in response"
echo "Response : $RESPONSE"
exit 1
fi
# 5. Save the direct HTML code to a file
echo "$HTML_CODE" > "_site/$filename.html"
echo "✅ Page $filename.html generated."
done
if [ -f "_site/README.html" ]; then mv _site/README.html _site/index.html; fi
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: '_site'
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Key points to remember:
- {{secrets.SAAS_APP_AUTH}} : This is a secret variable that must contain your application's API token in the Super Markdown platform.
- {{FOLDER_NAME}} : This variable must specify the name of the folder where the converted Markdown documents will be stored within the Super Markdown platform.
- {{MODE}} : It's variable to identify the color mode to apply to documents converted by Super Markdown; it accepts (light-mode, dark-mode).
Technical Architecture
The final result is displayed in an HTML page with all the necessary assets (such as CSS, JavaScript, and images) and is deployed on the Super Markdown Platform. This architecture offers several advantages:
- Reduced storage: Resources (CSS, JavaScript, images, SVGs) are not hosted on your GitHub repository.
- Simplified maintenance: No manual management of static resources is required.
- Rapid deployment: The process is automated via GitHub Actions.
- Updates: No action is required to obtain the latest component updates UI and deploy new ones.
Page navigation management
The workflow described above automatically handles:
- Compiling Markdown content
- Rewriting URLs to ensure smooth navigation between pages.
- Maintain the SEO of your pages for greater visibility of your documentation and guides in search engines.
What's Next ?
- AI Agent Support : Getting Started with AI Agent Support
- Advanced Usage : Learn more about custom templates and Reuse them.
- Best Practices : Tips for building professional documents at scale
Need help ? Our team is here to support you. Contact us or check our FAQ.