POC Astro

[digitaldiina]

...Just a place to keep notes pertaining to Astro

Why switch platform?

• Build time
• Rendering time, especially in API references and when embedding images
• DocFx's templating system is complex to use
• Easy dark mode
• Mermaid diagrams

Why Astro?

• Faster prod build and rendering (An Astro website can load 40% faster with 90% less JavaScript than the same site built with the most popular React web framework.
• Instant preview of dev build in VS Code
• TypeScript type-safety for Markdown content
• Component-based design
• Template system with JSX-like expressions
• Opt in to complexity
• Opt in to client-side rendering only if, and exactly as, necessary
• Active community on Discord
• Internationalization (i18n) features: default language and fallback
• Switch to tailwind CSS (official integration)
• Display optimized versions of images
• Enable pre-fetching (When you hover over the link, the script will fetch the page in the background.)
• Can use MDX if we want to
• Free choice of UI Framework (such as @astrojs/react)
• Easy integration setup/upgrade with npm
• Can use rediredct_from list in the new file - without keeping 1:1 mapping in the old md files. (This avoids clutter of placeholder files)
• Remark plug-ins

[digitaldiina]

Platform wishes

• SuperOfficeDocs/superoffice-docs#356
• SuperOfficeDocs/superoffice-docs#550
• SuperOfficeDocs/superoffice-docs#1038
• SuperOfficeDocs/superoffice-docs#575
• https://github.com/SuperOfficeDocs/build-docs/issues/56
• https://github.com/SuperOfficeDocs/build-docs/issues/51

[digitaldiina]

UI wishes

• SuperOfficeDocs/superoffice-docs#368
• SuperOfficeDocs/superoffice-docs#369
• SuperOfficeDocs/build-docs#104
• SuperOfficeDocs/superoffice-docs#1154
• SuperOfficeDocs/superoffice-docs#953
• SuperOfficeDocs/superoffice-docs#554 (responsiveness)
• SuperOfficeDocs/superoffice-docs#557 (responsiveness)
• https://github.com/SuperOfficeDocs/build-docs/issues/72
• https://github.com/SuperOfficeDocs/build-docs/issues/73
• https://github.com/SuperOfficeDocs/build-docs/issues/75
• https://github.com/SuperOfficeDocs/build-docs/issues/76
• https://github.com/SuperOfficeDocs/build-docs/issues/77
• https://github.com/SuperOfficeDocs/build-docs/issues/78
• https://github.com/SuperOfficeDocs/build-docs/issues/79
• https://github.com/SuperOfficeDocs/build-docs/issues/80

[digitaldiina]

Content wishes

• SuperOfficeDocs/superoffice-docs#667
• SuperOfficeDocs/superoffice-docs#668
• https://github.com/SuperOfficeDocs/build-docs/issues/86

[digitaldiina]

Features

• Search - with AI?
• Top menu
• Left-side toc with filter on article and tutorial pages (handcrafted)
• Language selector
• In this article (auto)
• Related content (handcrafted)
• Breadcrumbs
• Edit page, Feedback, and Site feedback
• Content info with version, time-to-read, audience, onsite/online, pilot
• (Sub)Category pages
• Homepage
• Footer with copyright and links
• Redirects
• "Stable" links for the dispatcher
• Sitemap exported to In-App

[digitaldiina]

Markdown

• [ ] Frontmatter metadata
• [ ] Admonitions (tip, note, caution, warning)
• [ ] Tables with left/center/right aligned cols (rows automatic alternating colors)
• [ ] Tabbed content
• [ ] Inline code with single backticks
• [ ] Fenced code blocks with triple backticks
• [ ] Includes (for reuse)
• [ ] Includes (code-snippets with DocFX Flavoured Markdown)
• [ ] Paths relative to current md/yml file
• [ ] Reference-style links and images
• [ ] xref-style links (uid)
• [ ] Optional explicit anchor on headings
• [ ] Bookmark links (anchors)
• [ ] Expandable content (used only 5x)
• [ ] <script> tag to embed forms from SuperOffice
• [ ] Markdownlint

[digitaldiina]

Content and data formats

• Markdown
  • Articles
  • Release notes
  • Contribution guide
  • NetServer config
  • RESTful (Agents, REST)
  • SOAP (Services88 osv)
  • Archive providers
  • MDO providers
• Yaml (custom)
  • Homepage
  • Category page
  • SubCategory page
• YAML ManagedReference
  • CRMScript
  • NetServer Core and Services
  • SuperOffice.WebApi
  • SuperOffice.DCF.Web
• JSON
  • Map src files to output folders (DocFX build file)

[digitaldiina]

Things we can measure and compare

• Page load performance
• Build time (both prod and localhost)
• Publication time

[digitaldiina]

Integrations

• @astrojs/tailwind
• @astrojs/sitemap
• @astrojs/mdx
• @astrojs/react
• astro-compress
• astro-navbar
• astro-pagefind
• astro-i18next
• astro-breadcrumbs
• accessible-astro-components
• astro-page-insight
• astro-social-share
• astro-robots
• cookieconsent
• astro-toolkit
• astro-custom-toc
• astro-redirect-from
• tailwindcss-typography