Define technical components for entire system.

[bwklein]

General specs for each component of a system.

• Content - storage tech, source control, file management, and source file formats (Github, GitLab, Headless CMS, etc.)
• Transformer - source to target formats (MD -> HTML or ADOC -> HTML & PDF or MD -> HTML -> PDF with goldmark, pandoc, asciidoctor, etc.)
• Assembler - target formats organized into a coherent structure/relations (Hugo, Antora, SSGs, SvelteKit, Next.js, etc.)
• Distribution - web server, file sharing, embedded system, etc. (Netlify, S3+Cloudfront, CDNs, etc.)
• Automations - CI/CD or something to glue the components together. (GitLab CI/CD, Github Actions, Netlify Builds/Deploy, etc.)
• Others?

The idea here is to identify the requirements for a complete system that can be replaced per implementation.

[bwklein]

Setup the Netlify template to help someone clone to a new repo and host their site on Netlify. https://templates.netlify.com/

[mgan59]

Liking the list here you started. Especially Distribution indicating if it has an easy deploy option/template for Netlify, Vercel, Heroku, or S3+Cloud front. Think everything else here is good and I think you've done a great job covering the various characteristics 💯

I think once we model a few of these out we may see some boundaries that may help tight the scope -- for instance assembler versus automations think there could be some blurring between them. and I think Content may also need to indicate what format it is stored (markdown, asciidoc, etc) so that it matches the transformer(s) category.

[bwklein]

for instance assembler versus automations think there could be some blurring between them

Here is an example that comes to mind:

• Content
  • storage tech = GitLab
  • source control = Git, with 'staging' and 'main' branches for editorial flow.
  • file management = GitLFS for binary files (images, videos, zips, PDF, xlsx, docx) in 'uploads' folder
  • source file formats = HTML, CSS, JS, JSON, CSV, YAML, TOML, MD, ADOC
• TGDP Templates
  • Hugo 'archetypes'
  • Content Types/Templates in FrontMatter CMS extension configuration
• Transformer
  • sources = MD, ADOC
  • targets = HTML, PDF
  • tech = Goldmark (built into Hugo), Asciidoctor
• Assembler
  • Hugo
• Automations
  • Netlify Builds with Webhook trigger on GitLab repo branch changes
• Distribution
  • web server = Netlify
  • images/videos = Imgix, with the folder /uploads/ set as the Imgix 'Source'
• Project
  • name = Hugo Starter
  • projectURL = https://gitlab.com/zivbk1/hugostarter
  • license = MIT
  • license URL = https://gitlab.com/zivbk1/hugostarter/-/blob/main/LICENSE

[mgan59]

I drafted one for Docusaurus

• Content
  • source control = git
  • storage tech = GitProviders: ['gitlab', 'github']
  • file management = Standard File System
  • source file formats = md, mdx
• TGDP Templates
  • Docusaurus reads from /docs with sub-folders as categories so it would support a taxonomy of docs/guides or docs/how-tos from TGDP.
  • Supports Front-Matter Capabilties: tags, title, keywords, etc
• Transformer
  • sources = MD, MDX
  • targets = HTML
  • tech = Typescript, Remark
• Assembler
  • Docusaurus -- custom cli docusaurus build
• Automations
  • Netlify Builds with Webhook trigger on GitProvider repo branch changes
  • Github Action available for github-pages
• Distribution
  • Self-Hosted: S3+Cloudfront or alternative cloud-provider.
  • JAM-Stack: Netlify, Vercel, etc.
  • StaticFiles: images from /public folder are bundled as part of build and can be configured.
• Features
  • Search: Algolia
  • Additional/Custom Pages: Yes
  • Multi-Version Docs: ?
• Project
  • name = Docusaurus
  • projectUrl = https://github.com/facebook/docusaurus
  • License = MIT
  • LicenseUrl = https://github.com/facebook/docusaurus/blob/main/LICENSE
  • Description = Facebooks react static-site generator built specifically for developer documentation sites and portals
  • monoRepo = true

[mgan59]

Potential version for the gitbabel starter-kit

for instance assembler versus automations think there could be some blurring between them

Here is an example that comes to mind:

• Content
  • source control = git
  • storage tech = GitProviders: ['github']
  • content-management = Standard File System & GraphQL
  • source file formats = md, mdx, graphql
• TGDP Templates
  • Supports .gitbabel/config in repository see docs to auto-index templates.
  • Supports Front-Matter Capabilties: tags, title, topicType which gitBabel supports topicType and can map TGDP template files to indicate their type such as reference, guides, tutorial
• Transformer
  • sources = MD
  • targets = HTML
  • tech = TailwindCSS, NextJS, ApolloGraphQL
• Assembler
  • NextJS + gitBabel
• Automations
  • Netlify Builds with Webhook trigger on GitProvider repo branch changes
  • Github Action available for github-pages
  • Github App - required if pull-request, issues, and other github markdown streams to be accessed.
• Distribution
  • Self-Hosted: S3+Cloudfront or alternative cloud-provider.
  • JAM-Stack: Netlify, Vercel, etc.
  • StaticFiles: images from /public folder are bundled as part of build and can be configured.
• Features
  • API / Search: GraphQL
  • Additional/Custom Pages: Yes
  • Code-Syntax Highlighting: Yes / Prism
  • Multi-Repository: Yes
  • Multi-Version Docs: Yes
  • Preview-Branch-Support: Yes. [paid]
  • Authentication: Github OAuth [paid]
• Project
  • name = gitBabel Starter-NextJS-TailwindCSS
  • projectUrl = https://github.com/gitbabel/starter-nextjs-tailwindcss
  • License = MIT
  • LicenseUrl =
  • Description = A Starter Kit
  • monoRepo = true

[sivaraam]

About the technical components for docusaurus:

• Multi-Version Docs: ?

I suppose Docusaurus does support multiple versions of docs. See Versioning | Docusaurus