Live demo : https://microwebstacks.github.io/astro-big-doc/
Astro Theme for big documentation websites. Hierarchical pages menu from files structure and table of content, Markdown rendered as CMS with Astro components for panzoom, 3D, links, interactive tables, diagrams from code, VSCode like highlighter.
Enhances native markdown '.md' files with Astro components, enables parsing of content from a configurable directory in the file system, and allows relative assets paths usage.
User friendly side menus collapsible and width adjustable with the mouse.
- enhance images with panzoom function
- image directive for images size defintion in markdown
- use relative assets in markdown
- Active data tables with DataTables
- from Markdown table
- from xlsx file link
- 3D Model viewer
- from .glb link
- from yaml parameters
- external links identification and rendering with an arrow
- VSCode like highlighting using Shikiji
pnpm install
pnpm run dev
pnpm run build
- test locally with https://nektosact.com/installation/index.html
for development of content-structure it is possible to replace the registry version with the submodule version
"content-structure": "file:packages/content-structure",
-
support different icon types (.svg, .ico, .png) and allow it in content root
-
top readme.md in content used as home
-
public folder inside content and ignored by content structure
-
.structureignore to allow e.g. .git/workflow/deploy.yaml
-
test mixture of readme page with filenames and folders
-
fix consistency of top menu folder name different than slug
-
Code
- keep separate plantuml and kroki (due to perf reason)
-
SVG
- meta data from filename.yaml or (code meta).yaml
- list of links : label, link
- list of dependencies : map, highlight list on key hover
-
PanZoom
- URL params, zoom on text, multiple hits counter
- update pan zoom status in url on mouse up
-
check potential replacement of scrollspy with intersection Observer API
- enhance intersection to cover a path of all visible sections from the page in the toc : start heading, stop heading
-
light and dark mode toggle
-
sync with Astro utilities for url resolution and astro image integration
-
Gallery
- Expand open close with images inside
- dynamic adjust on container resize
- scale items
- can use thumbnails, no search to avoid double hit
- click to open panzoom with images mini thumbs
-
menus
- store menu scroll position
- store menus width
- use view transition to give menu persistence impression on page navigation
-
content Structure
- parse yaml tags and orgnaize menu with tags order hierarchy
-
caching
- SSR render on page hash condition, using ETag
- page hash with depndencies hashes, include assets hash as attribute
-
menus
- ToC auto-expand : open scroll spy, close all others
- Left and right : min (disabled) or expand to level slider or selector
- Left and right : auto expand depth adjust to available vertical space (all level or nothing)
- pages types and icons
- open close on nav-resize click
- Issue: Menu height transition MUI example is working
- User content can be placed in a configurable relative path to the repo root usually
./content
set in these variables- config.content_path
- config.collect_content.contentdir
- Zerop copy assets management
- during dev, an API endpoint exposes
./content/*
under/assets/*
- during dev, an API endpoint exposes
- Generated content by pages frontmatter (e.g. svg diagrams from code and text code for highlighter client copy) :
./public/codes/*
during dev, served under/codes/*
with./src/pages/codes/[...path].js
./dist/codes
during build, served under/codes/*
- Note : since Astro4/Vite5
./public/*
does not watch and serve newly generated content by pages frontmatter, that's why an endpoint API is needed
- Generated content by integrations
- if only needed by the integration or pages build then gets generated in
.structure/
folder (e.g.documents_list.json
,...) - the menu needed by the client gets generated in config.collect_content.out_menu
./public/menu.json
for both dev and build served on/menu.json
- Note : integrations cannot directly generate on
dist
because they cannot persist there before start of build
- Note : integrations cannot directly generate on
- if only needed by the integration or pages build then gets generated in
-
SVGs
- if missing viewbox canot be resized
- should not have
preserveAspectRatio="none"
-
menu config allows index pages but do not use them to keep consistent nav menu of folders/items
-
adding interactive SVGs that can be styled with css is challenging
svg.astro
uses the innerHTML fragment which breaks visibility ofstyle
tag no longer scoping imported SVG- import of
rightarrow.astro
still requires style to be either global or inline - Tree menu collapse transition :
- display block/none does not animate the height
- scaleY does not bring the height down to 0 due to remaining padding margin
- height can be animated but must be set initially
- max-height can be animated but must be set to max value which breaks the transition timing
- max-height adjusting with js requires high complexity depending on state of expanded children hierarchy
- clip also needs defined start stop
- flex can also animate but then the flex container height must be set explicitely
-
express subdomain usage instead of
app.use(express.static(outdir))
use
app.use(testRouter)
app.set('subdomain offset', 1); // Adjust based on your domain structure
app.use((req, res, next) => {
const subdomain = req.subdomains[0]; // Get the first subdomain
switch (subdomain) {
case 'website1':
express.static(outdir)(req, res, next);
break;
default:
next(); // Continue to other routes if no subdomain matches
}
});
Express server in server\server.js
can optionally be used to serve the generated static site. It adds an authentication layer on top using Express passport.
This project uses environment variables as unified config to astro.config.mjs and to the express server. The environment variabels are also loaded by a config.js
to allow their usage from any file in astro including .js
It is possible to build with zero config, the default mode is 'STATIC' See also an example in .env.example.
Astro variables
OUT_DIR
: directory where the build will be genratedPORT
: maps to astro.config.mjs server.port
Express general variables
PROTOCOL
: either of htp or https for express server usageCERT_FILE
: required when https is usedKEY_FILE
: required when https is used
Express authentication variables
HOST
: Express passport callbackURLPORT
: Express passport callbackURLGITHUB_CLIENT_ID
: Express passport Github strategy configurationGITHUB_CLIENT_SECRET
: Express passport Github strategy configurationSESSION_SECRET
: used by 'express-session' handler
-
Github OAuth : https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps
-
express-session :
-
passport OAuth doc : http://www.passportjs.org/concepts/authentication/oauth/
-
passport-github : https://github.com/jaredhanson/passport-github
-
passport-github doc : http://www.passportjs.org/packages/passport-github/
-
passport example : https://github.com/passport/todos-express-facebook/blob/master/app.js
-
jwo example : https://gist.github.com/jwo/ea79620b5229e7821e4ae61055899cf9
-
using self signed keys with
server/create.sh
result in browser warning 'your connection is not private' (NET::ERR_CERT_AUTHORITY_INVALID) -
for 'Let's Encrypt' certificates, ownership has to be proven by visibility of the host from the public internet which makes it not usable for internal domains and local network hosts
- https://github.com/syntax-tree/mdast
- https://github.com/syntax-tree/mdast#code
- https://github.com/syntax-tree/mdast#html
- https://github.com/remarkjs/remark/blob/main/doc/plugins.md
- https://github.com/syntax-tree/unist-util-visit
- https://github.com/akebifiky/remark-simple-plantuml
- MIT
- https://www.svgrepo.com/svg/19947/folders
- https://www.svgrepo.com/svg/400563/openfilefolder
- https://freesvg.org/1542512156 : tree
- https://www.svgrepo.com/svg/75085/full-screen
- https://uxwing.com/text-file-icon/
- title conflicting with path, url and slug in
create_raw_menu()
- diagrams
- generate diagrams from image url and extension
- graph properties through code block arguments