lion/astro.md

Astro Starter Kit: Minimal

npm create astro@latest -- --template minimal

🧑‍🚀 Seasoned astronaut? Delete this file. Have fun!

🚀 Project Structure

Inside of your Astro project, you'll see the following folders and files:

/
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json

Astro looks for .astro or .md files in the src/pages/ directory. Each page is exposed as a route based on its file name.

There's nothing special about src/components/, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.

Any static assets, like images, can be placed in the public/ directory.

🧞 Commands

All commands are run from the root of the project, from a terminal:

Command	Action
npm install	Installs dependencies
npm run dev	Starts local dev server at localhost:3000. Note comment out/ uncomment the remarkPlugins: related to either ing-web or lion portal in astro.config.mjs
npm run build	Build your production site to ./dist/
npm run preview	Preview your build locally, before deploying
npm run astro ...	Run CLI commands like astro add, astro check
npm run astro -- --help	Get help using the Astro CLI

👀 Want to learn more?

Feel free to check our documentation or jump into our Discord server.

Site search integration by PageFind

Pagefind is a fully static search library that aims to perform well on large sites, while using as little of your users’ bandwidth as possible, and without hosting any infrastructure. The feature is advertised by Astro website: Astro Starlight Site Search Guide

How it is integrated

• Note, follow Pagefind documentation for more details. For tests purposes, add a UI markup to any astro page to enable search component on a page:

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js" is:inline></script>
<div id="search"></div>
<script is:inline>
    window.addEventListener('DOMContentLoaded', (event) => {
        new PagefindUI({ element: "#search", showSubResults: true });
    });
</script>

How to run

• Run npm run build to generate static html files
• Run npm run pageFind to index static html files in dist folder and generate files in dist/pagefind/ that we import in the UI search component part in the snippet above. Note, the UI search component will not show up on the page if this step is not run
• Run npm run preview. This will run the app from the dist folder

Migration of ing-bank/lion/packages-node

rocket-preset-extend-lion-docs

• It is not possible to use rocket-preset-extend-lion-docs out of the box. The reason is that its code relies on some Rocket specific global JS variable names (f.e. plugins variable in node_modules/plugins-manager/src/addPlugin.js). Also it specifies the order among existing plugins to inject the its internal plugins (see more for details rocket-preset-extend-lion-docs source). We can't reuse that order. Same applies to the dependent remarkUrlToLocal plugin. To integrate rocket-preset-extend-lion-docs the following steps were done:
  • src/utils/remark-plugings/wrapper-for-rocket-preset-extend-lion-docs/assets contains the patched files taken from the original plugins. Then during the installation those files are copied to node_modules. The script for copying is defined in src/utils/remark-plugings/wrapper-for-rocket-preset-extend-lion-docs/copy.sh and it is currently triggered by postinstall command in package.json
  • src/utils/remark-plugings/wrapper-for-rocket-preset-extend-lion-docs/wrapper.js contains a copy of P00019-ing-web/rocket.config.mjs. That is configuration setup where we specify the replacement rules. F.e here we specify that <lion- should be changed to <ing-button.

remark-extend

remark-extend is setup by src/utils/remark-plugings/wrapper-for-rocket-preset-extend-lion-docs/wrapper.js

babel-plugin-extend-docs

babel-plugin-extend-docs is setup by src/utils/remark-plugings/wrapper-for-rocket-preset-extend-lion-docs/wrapper.js

How to migrate components documentation

Lion Portal

In this section there are steps for migrating a component directly from lion/docs to Astro portal. For the sake of the example let's migrate a button component from lion/docs/components/button. Here are the steps:

• Migrate assets and extensions

  • In this repo create a directory called public/components/button. The name should match the component directory name. Note files in /public directory are going to be available at runtime by URL host:port/. F.e. public/components/button/src/icon.svg.js is available by URL host:port/components/button/src/icon.svg.js
  • Copy all assets into the created directory from the Lion repo. These files need to be copied:
    • public/components/button/extensions/BootstrapButtonTypes.ts
    • public/components/button/extensions/bootstrap-button.mjs
    • public/components/button/src/icon.svg.js
  • Inside the copied files replace the imports for js/mjs files so that the files which are located in node_modules, imported directly from node_modules:

    • Inside bootstrap-button.mjs replace

      import { LionButton } from '@lion/ui/button.js';
      import { css } from 'lit';
      

      with

      import { LionButton } from '/node_modules/@lion/ui/button.js';
      import { css } from '/node_modules/lit';
      

• Migrate docs

  • In this repo create a directory called src/content/demo/button. The name should match the component directory name
  • Copy all md files into the created directory from the Lion repo
  • Inside md files identify all imports inside the blocks wrapped by the ```js script block.

    • Replace all relative imports. F.e. in button/examples.md replace

      import iconSvg from './src/icon.svg.js';
      

      with

      import iconSvg from '/components/button/src/icon.svg.js';
      

    • The imports which refer to node_modules should stay untouched. F.e. import { html } from '@mdjs/mdjs-preview'; should not be changed

• Update Astro configuration

  • Go throught every md file in src/content/demo/button andjs, mdjs file in public/components/button/,
  • Copy the js file name that are imported and then
  • Add those file name into Astro-Lion integration here: src/utils/astrojs-integration/lion/lion-integration.js

Ing-web Portal

• Follow all the steps from Lion Portal section but for components located in P00019-ing-web/docs/components
• Replace all relative imports that refer to a package in node_modules as follows: replace import '#define/ing-button.js'; with import 'ing-web/button.js';

Futher improvements

• Propose the solution where the existing docs directory is kept untouched (or almost untouched) and via the build script all the files are copied to the structure Astro requires. That way we can keep the relative paths and it will make the development experience almost the same as now
  • Note. Consider the watch feature. Whenever any file inside docs is changed, Astro rerender those changes as it happens now on Rocket
  • Note. docs might be put into content directory. Then every md file should be provided with the proper tas, such as: component, category (Development, Changelog, Design), platform (web, ios, android). Those are required to render based on secondary navigation input (category + platform)
• In the current setup the ing-web is installed as a dependency as is referred as node_modules/ing-web. Should it instead be refered as packages/ing-web
• Update rocket-preset-extend-lion-docs and remarkUrlToLocal properly. See details in the Migration of ing-bank/lion/packages-node section.
• With the current limitation of having one md file per route, consider combining file mantually for the same route. F.e. on lion there is directory docs/components/button. That one contains multiple md files. And all those are for web platform. Consider combining those to one web.md file. The proposal assumes that there will be docs for the multiple platforms and then the doc for Design and Changelog.
  • As a consiquence update the way in-page navigation (right side menu) works. It shdould be updated as follows:
    • Build the menu dynamically based on H2 tags found on the page
    • Write a remark plugin or reuse existing one to add anchor tags with IDs for every ## hearder
• src/utils/remark-plugings/wrapper-for-rocket-preset-extend-lion-docs/wrapper.js contains some replacement pattern based on the URLs used in Rocket. We need to review those replacements according to our new endpoints
• What is docs/components/button/status.mjs and how we reuse it?
• rocket-preset-extend-lion-docs should be cleaned up from everything related to Rocket. The name Rocket should gone