From 56848d4371a8ce1d0cc11fcc22055c7a63d2b7d5 Mon Sep 17 00:00:00 2001 From: DerDieDasDeakin Date: Fri, 15 Dec 2023 16:55:40 +1030 Subject: [PATCH] Save the Sidebar State Report This report details the time spent attempting this and the discovery of issues when it comes to overriding .astro components. If the override problem can be solved, then this task can be completed as the current custom Sidebar.astro file will successfully save the state of the sidebar. --- ...ar-and-Component-Override-Spike-Outcome.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 src/content/docs/products/splashkit/documentation/SplashKit-Starlight-Wesbite-Sidebar-and-Component-Override-Spike-Outcome.md diff --git a/src/content/docs/products/splashkit/documentation/SplashKit-Starlight-Wesbite-Sidebar-and-Component-Override-Spike-Outcome.md b/src/content/docs/products/splashkit/documentation/SplashKit-Starlight-Wesbite-Sidebar-and-Component-Override-Spike-Outcome.md new file mode 100644 index 00000000..c699ca5a --- /dev/null +++ b/src/content/docs/products/splashkit/documentation/SplashKit-Starlight-Wesbite-Sidebar-and-Component-Override-Spike-Outcome.md @@ -0,0 +1,128 @@ +--- +title: SplashKit Starlight Website Sidebar and Component Override Spike Outcome +--- + +**Spike:** NA + +**Title:** SplashKit Starlight Website Sidebar and Component Override Spike Outcome + +**Author:** Frankie Veri, s222371429@deakin.edu.au, + +## Goals / Deliverables + +The goal of this task was to investigate a way to save the state of the starlight website sidebar, +with a larger goal of finding a way to override astro components without error to allow for better +customisation. + +## Technologies, Tools, and Resources used + +- Internet Browser: Chrome +- Programming Languages: JS, HTML +- Visual Studio 2022 +- Visual Studio Code +- Programming Libraries: SplashKit +- Astro Framework +- Starlight Template +- Text Editor: Notepad +- Terminal + +## Tasks undertaken + +The following are the tasks that were performed to produce this report. A lot of +research and experimentation were also conducted, which I will briefly discuss. + +### JavaScript localStorage, sessionStorage, and Cookies + +- In my first attempts to save the state of the sidebar + I looked into using the JS methods of localStorage, sessionStorage, + as well as cookies. +- Due to the sidebar's reliance on downloaded astro dependencies, + I couldn't achieve this method of implementation without big changes + to the website's framework. +- Astro also has current limitations with cookies. +- Testing the website would result in the browser not registering the + storage or cookies as a result. + +### Git Sidebar Persistence Request + +- A Pull Request was found under the Starlight Git which looked to + achieved a similar result. +- This PR does work with the current Splashkit website in testing, + however, it needs to be made a permanent addition. +- The URL below will bring you to this PR + https://github.com/withastro/starlight/pull/1121/files + +#### Override Changes and Attempts + +- I used the below URL as a guide for the following, as it gave + me instructions on how to override astro components with custom ones. + https://starlight.astro.build/guides/overriding-components/ +- The code below was added to the astro.config in order to override: +``` +components: { + //Override the default `Sidebar` component. + Sidebar: './src/components/Sidebar.astro', +}, +``` +- This would result in the following error +``` +Could not import ./SidebarSublist.astro. + +``` + +- Adding the 'SidebarSublist.astro' file to the 'src/components' directory + would result in the following error: +``` +Could not import ../utils/navigation. + +``` +- Adding the 'navigation.ts' file would then cause the following: +``` +Could not import ./createPathFormatter. +``` +- On occasion it will throw an 'unexpected character' error. Otherwise, + it will always be searching for extra imports. + +### Importance of Task and Report + +- This task, if completed, could allow for immense customisation of the starlight + website. +- It would allow for us to override other components and make extra important changes. +- Due to being pressed for time, it was here that testing and troubleshooting ended, resulting + in this final report for work to resume. + +This report is the product of hours and hours of testing and troubleshooting, so the scope of the final +task is not known. It may be larger than expected. + +## What we found out + +That major changes like this are possible, but they need to be done within the astro framework. If this works, +we could enhance the website in almost any way that we wanted, allowing for extra customisable options. + +#### What worked + +Replacing the default 'Sidebar.astro' in '.\node_modules\@astrojs\starlight\components' does work. +This change will allow you to test the custom 'Sidebar.astro' file and allow you to save the state of the sidebar. +The website seems to recognise the attempt to override the default component but struggles to find the rest +that we do not wish to override. + +#### What wasn't tested + +Any additional attempts to get the 'override' function to work. Several hours were spent troubleshooting, +but there could be a lot more done that wasn't tried. + +#### What didn't work + +Using JS to save the bar did not work. Following the override guide also did not work. + +## Open issues/risks + +The permanent changes have yet to be complete, as I cannot currently find a way to get the website +to recognise the non-overridden components. I don't know if there are larger or unknown issues at play +here. This will need to be investigated further. + +## Recommendation + +Currently, I recommend investigating why the override function is not working, as it should based on +the official tutorial. Extra troubleshooting will be required, as well as possibly testing this with +smaller components. Beyond this, I am currently not sure how to fix this issue.