• SSG
• VuePress
  • theme hope
• VitePress
• MkDocs - Python
  • mkdocs.yml
• properdocs = MkDocs v1
• for Blogs
• Pelican - Python
• for Wiki
• Sphinx - Python
  • Themes
  • Static Files
  • Table
  • Diagrams

SSG¶

• https://docs.astro.build/en/guides/migrate-to-astro/#migration-guides

• https://github.com/myles/awesome-static-generators

• Jekyll theme with search : https://github.com/just-the-docs/just-the-docs

• Antora: multi repo into 1: https://docs.antora.org/antora/latest/
• Jupyter: https://curvenote.com/docs/web/notebooks

• RMarkdown: https://rmarkdown.rstudio.com/docs/reference/publish_site.html

  echo -e ‘# Heading \n contents’ > index.md

  npx @pruddiman/mdmirror ./ –host 0.0.0.0 –port 8008 # sidebar + search

  npm i -g docsify-cli –ignore-scripts docsify init # + README.md & index.html(cdn js/css) docsify serve ./ –host 0.0.0.0 –port 8008

  npm install @11ty/eleventy -g npx @11ty/eleventy –serve –port=8008 # localhost , cli no –host

VuePress¶

https://vuepress.vuejs.org/guide/getting-started.html

bundler: viteBundler({
  viteOptions: {
    server: {
      allowedHosts: true,
    },
  },
}),

theme hope¶

auto sidebar & search when dev: https://theme-hope.vuejs.press/guide/layout/sidebar.html#grouping-and-

// .vuepress/config.ts
import { viteBundler } from "@vuepress/bundler-vite" # then same above

// .vuepress/theme.ts

pageInfo: false,  // will hide : author / page-reading-time-info

plugins: {
  comment: false,

sidebar: {
"/": [
  {
    text: "",            // Leave blank so it acts purely as a structural wrapper
    icon: "",            // Optional icon
    collapsible: false,  // Disables collapsing globally for all auto-generated groups
    children: "structure", // Automatically builds the sidebar from your directory
  },
  ],
},


# .vuepress/styles/palette.scss
/* 桌面端侧边栏宽度（默认 20rem） */
$sidebar-width: 12rem;

/* 移动端侧边栏宽度（默认是 20rem × 0.82） */
$sidebar-mobile-width: 10rem;

VitePress¶

https://github.com/vuejs/vitepress

https://vitepress.dev/guide/getting-started

MkDocs - Python¶

mkdocs.yml¶

• https://github.com/mkdocs/mkdocs/blob/master/mkdocs.yml
• https://github.com/mkdocs/mkdocs/blob/master/mkdocs/tests/integration/complicated_config/mkdocs.yml
• https://gitlab.liris.cnrs.fr/pagoda/tools/mkdocs_template/-/blob/develop/user_config/mkdocs.local.yml

properdocs = MkDocs v1¶

echo 'properdocs<2 properdocs-theme-mkdocs' | sed "s/ /\n/g" > requirements.txt
pip3 install -r requirements.txt

echo "site_name: My Docs" > properdocs.yml
echo "# header" > docs/index.md
properdocs serve

for Blogs¶

Pelican - Python¶

Markdown, reStructuredText, and HTML - default theme -> blog : https://www.smashingmagazine.com/ - https://github.com/getpelican/pelican - https://docs.getpelican.com/en/latest/index.html#documentation

for Wiki¶

Sphinx - Python¶

reStructuredText -> HTML, PDF, plain text, EPUB, TeX - Start: https://www.sphinx-doc.org/en/master/tutorial/getting-started.html - toctree options: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

GraphiQL: https://github.com/hasura/sphinx-graphiql

Themes¶

Builtin: https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes - only the Alabaster and Scrolls themes are mobile-optimated

Templating/blocks: https://www.sphinx-doc.org/en/master/development/templating.html#blocks

Read the Docs theme with custom footer: https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/footer.html

html_show_sphinx = False # conf.py

# %templates_path%/footer.html    
{% extends "!footer.html" %}
{%- block extrafooter %}

{% endblock %}

Static Files¶

https://www.sphinx-doc.org/en/master/usage/configuration.html - html_static_path / html_css_files / html_js_files - html_additional_pages: .html files

Table¶

https://docs.espressif.com/projects/esp-docs/en/latest/writing-documentation/table.html - span: https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table

Diagrams¶

https://chiplicity.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html