Utility for XiangShan Document

This repository contains the utilities and resources needed to build XiangShan's standardized Document.

Contents

Pandoc building environment dependency script

The script dependency.sh sets up the environment for pandoc builds.

• Pandoc and its filters:
  • pandoc-crossref with corresponding version
  • include-files
• TinyTeX and some LaTeX Package:
  • ctex, setspace, subfig, caption, textpos
• Fonts:
  • Source Han Sans
• Other dependencies:
  • librsvg2-bin for SVG processing

Pandoc Template

Customized pandoc templates for HTML and LaTeX.

Pandoc Lua filters

All Pandoc Lua filters are located in pandoc_filters.

• remove_md_links.lua:

  Remove links pointing to Markdown files (*.md), which is useful for one-file project.

• replace_variables.lua:

  Replace placeholders (e.g. {{foo}}) in Markdown with their corresponding value (e.g. bar) defined in metadata.

  Example of metadata yaml:

  replace_variables:
    foo: bar

• svg_to_pdf.lua:

  Change referenced SVG format images to their corresponding PDF format images, which is useful for LaTeX builds.

MkDocs building environment requirements

The script requirements.sh defines requirements for MkDocs building.

• MkDocs-Material
• Python-Markdown extensions:
  • markdown_grid_tables
  • markdown_captions
  • caption
  • The following Python-Markdown extensions

Python-Markdown extensions

All Python-Markdown extensions are located in mdx_extensions folder and used in MkDocs builds.

• remove_include.py:

  Remove Pandoc include-files style include code blocks.

  ``` {.include}
  file1.md
  file2.md
  ```
  

• remove_references.py:

  Remove Pandoc crossref with corresponding version style reference label like [@sec:foobar]

• replace_variables.py:

  Replace placeholders (e.g. {{foo}}) in Markdown with their corresponding value (e.g. bar) defined in extension config.

  Example of mkdocs.yml:

  markdown_extensions:
    - xiangshan_docs_utils.replace_variables:
        variables:
          foo: "bar"

Resources

• SVG and PDF format Logos of BOSC and XiangShan Community.

  These logos are all right reserved, and may not be used without permission.

LICENSE

This project is licensed under Mulan PSL v2 License, unless otherwise specified.

Copyright © 2024 The XiangShan Team, Beijing Institute of Open Source Chip