greenheart / idg.tools

Inner Development Toolkit - Transformational Skills for Sustainable Development

Inner Development Goals

Transformational Skills for Sustainable Development

Welcome! This is a collection of free and open source projects supporting the Inner Development Goals (IDGs). The goal is to accelerate the implementation of the Sustainable Development Goals (SDGs).

Our projects include:

• IDG.tools - A free, open source and co-created library of tools and resources to help people and organisations practice inner development.
• IDG.community - A website created by and for the IDG community. A place to share stories and get involved in various activities.

Contributing

First of all, thank you for being here! 🎉

We're a small team with high ambitions, and would love to get your help! This is only the beginning of what we want to create - an active open source community where people use technology to make meaningful contributions for a future where humanity and the living planet thrive together 🌱

Curious to learn how you can contribute? Come say hi in our chat rooms and we'll help you get started. There are many ways to help out so don't be afraid to ask!

• Get an overview of ways to contribute at https://idg.community/contribute
• Join our Element chat rooms:
  • IDG Localization Team
  • IDG.tools - design, content and development
  • IDG.community - design, content and development

Localization & translation

To support the emerging IDG movement to become truly global, we need to make the IDGs relevant and accessible to people all around the world. This is not just about translations - but more importantly, it's about adapting the content and language so it makes sense in your local context. And to make this happen, we need your help!

We use the IDG Community CMS to coordinate our localization efforts. Welcome to contribute!

Technologies used

• Svelte - One of the most approachable frontend web technologies, making development more accessible and fun.
• SvelteKit - Modern fullstack web app framework with a great developer experience.
• Netlify CMS - CMS to simplify both content co-creation and development, integrated with Git.
• Tailwind CSS - Simple and efficient styling, especially useful for rapid prototyping and collaboration.
• TypeScript - Simplifying maintainance as projects grow and needs change.
• Sharp - Image optimization to improve performance and reduce network bandwidth usage.
• pnpm - Fast, disk space efficient package manager.

Credits

• Icons by Heroicons
• Photos from Unsplash and Pexels. The original filenames have been preserved to make it easier to find the photographers (including names, photo ID and service).

License

The content of this repository is bound by the following licenses:

• The computer software is licensed under the AGPL-3.0 license.

• The content in the /content directory including their subdirectories thereon are licensed under the CC-BY-SA-4.0 license.

idg.tools's Issues

Visualize and support IDG hubs

Show a map with current known IDG hubs on the homepage.

• Basic info: City, Country, coordinates (to display on map)
• Contact details
• Link to Element chat room

In addition to the map, we could provide useful resources (basically markdown pages rendered on the webpage):

• what an IDG hub is (a grassroots group connected to a local area, who are practicing the IDGs to accelerate the implementation of the SDGs)
• how to join a hub
• how to start a hub in your local area if no one exists yet

Finally, we should feature relevant info on the landing page, plus around the app to encourage people to participate in and co-create a hub in their local area.

Setup user access rules to create different roles

Admin (can remove existing stuff)
Editor (can add new stuff and edit existing)
Public (no access)

Define structure of tools

A tool consists of:

• name
• description
• Call to action - one or more ways to use this tool into practice. For example "1) Do this course, 2) do this course with others to get more value"
• IDG relevancy scores
• resources (further exploration and background)

We also discussed level of scientific support that could use same relevancy score feature but different visual design. Ultimately we decided to use Research and resources instead to show the level of scientific support, and if we have few resource links for a tool, we show a disclaimer text with CTA to contribute with improved research and tool

Basically, the number and quality of linked resources will show the level of scientific support in a implicit and transparent way. It also removes the need to debate and maintain our own custom scientific relevancy score.

Sort relevancy scores for each tool when building content

Also throw an exception if there's a duplicate relevancy score, to prevent duplicates from showing up in the build. Or solve it with a validation check in the custom relevancy CMS field.

Automatically update tool links using CMS Events

This might enable similar functionality as hooks in Keystone, modifying content before saving.

https://www.netlifycms.org/docs/beta-features/#registering-to-cms-events

Another benefit is that we don't need to show everything in the CMS UI, but could keep the link and/or slug hidden in the background.

Make background image static

Background image expands when content expands, let's fix it to the height of the viewer/device

Consider replacing adapter-vercel with adapter-static

Since all content is static, it might be better to build at deploy time and serve a cached app.

CMS solution for easy content co-creation

• Keystone as headless CMS
• Anyone can discuss and submit content in our the IDG Tools chat room on Element
• Deploy Keystone to Heroku
• Possibly cache static content and do daily rebuilds of a static frontend, or when changes happen. Perhaps a GitHub action could be triggered once per day to rebuild the content and publish to github pages?
• Or use the GraphQL API to get real time updates.
• Setup access controls so editors only can edit and add new tools, and can't see other parts of the CMS. Admins can add/update/delete users, update categories and skills, and delete content. Perhaps add a review step before publishing, where admins can review and feedback changes.

Co-creator flexibility is a top prio to make this possible to scale.

Add possibility to render Markdown pages

This will be used for stories, IDG hub resources and more.

Maybe use https://mdsvex.com/

Idea: Maybe keep track of who has edited the content in the CMS, to generate a list of contributors

Why

By saving who has created, edited and reviewed content (specifically in the Tools collection) in the CMS, we could give credits to co-creators. This is important to encourage contributions and thank contributors for their work.

• To enable this, perhaps we could add more details on the Users collection where contributors can update their profile with a link and their name.
  • This would require unlocking the Users collection to all user roles, but only allowing access to your own user.
  • By allowing access to your own user, we also have the possibility that users can change their password themselves.

During the content build step, we should build the contributors and add to content.json.

Ideas for how to present this in the app:

• For each tool, list the contributors who have submitted an update to that tool.
• Centrally, on a contribute/community page we could feature the full list of co-creators.
• Idea is to combine with people contributing via GitHub, and fetch the latest data from there.
• Idea: Show the total number of co-creators involved. Maybe not exact number but more than X people have contributed to this resource
• Maybe generate unique graphic based on user email/id

Implementation ideas

• Maybe use some keystone hook that runs after successful create/update operations. This way we only track valid operations.
• Maybe add contributors as a relationship between tools and users. In the build step for content.json, or even in the app runtime, this could be combined into one large list.

Consider switching IDG skill and category IDs to slugified english names

This will greatly improve readability of the JSON files, and also make it easier to use raw IDs as values in the CMS relation widget.

This will slightly reduce the content JSON file size too since these IDs will be shorter than full cuids.

However, this won't make much sense for translations. Thus, perhaps an even better solution would be to use cuid.slug() for skills, categories and tags. yet another idea could be to use c1, s1 and t1 as IDs where the first letter is the content type.

Or we simply ignore this for now...

Make it easy for people to suggest new tools, content improvements and discuss all things related to IDG.tools

Ideas to explore:

1. Set up issue templates (forms?) to guide contributors to add a feature request or bug report or content suggestion.
2. Probably better: Set up GitHub Discussions for the project, to allow for greater flexibility.

Goals

• Make it easy to add content suggestions and start + maintain a discussion
• Allow different perspectives to be heard and seen (as long as they follow the community guidelines)

Fix Netlify CMS markdown/relation widget state update issues

Bug reproduction:

1. Open an entry in the CMS that contains a relation or markdown widget. For example any tool.
2. After 0.5 seconds, the top left button changes state and label to a red "UNSAVED CHANGES", despite nothing being edited yet.

Expected behavior

The top left button should not display the incorrect UNSAVED CHANGES, and the CMS should not prompt users to confirm before leaving the page.

Impact

This is quite serious since it will prevent the editorial_workflow mode in Netlify CMS from publishing changes, which is a bad UX for content co-creators.

Potential bug causes and research

• Seems to be related to decaporg/decap-cms#3039 and decaporg/decap-cms#2211
• Maybe caused by additional state updates triggered by the markdown or relation widgets. Or by custom components.

Potential workarounds

1. Maybe use a custom wrapper component to only trigger the onChange handler on actual content changes. decaporg/decap-cms#2211 (comment)

   • This might be possible to use both the relation and markdown widgets

2. Try to debug the actual issue in Netlify CMS and submit a PR with a fix.

Idea: Add scoring to each tool to show the level of scientific support

This will add credibility and transparency.

It will also allow us to include promising content without the same scientific support, while making it clear how it differs from the content with much stronger scientific support.

Could be represented as a number between 1 and 10 where 10 is the strongest support.

Write tests for the GraphQL API to define expected behaviors

Keystone has several testing utilities ready to use: https://keystonejs.com/docs/guides/testing#testing

They also have an example project from where we can borrow patterns: https://github.com/keystonejs/keystone/tree/main/examples/testing

@paccao Feel free to explore this if you're curious! ;)

Idea: Add relevancy score for each tool's related IDG skills

This will make it easier to distinguish tools to find not only relevent ones, but also the most relevant ones.

This will make the tools more useful.

Idea: show the 2-3 most relevant skills (with the scores with the highest relevancy score for their skill) in the explore page tool cards. Then "+2" that is toggleable to see all skills related to that tool. This would make the UI cleaner when adding many different relevant skills.

Update design to work for large screens too

Discuss what formatting options to support

Maybe remove bold and italics since it could be abused.

Maybe add headings to separate sections.

Show top resources by default, fade out and then a button to expand and show all

This will reduce the height of tools, and let the curious ones explore all resources, while keeping the main view more focused for people who just want to try the tool.

This will be a similar feature to how other limit/click to expand features work. Like expanding to show all skills.

Check the code here for an example of how to solve this task: https://github.com/Greenheart/idg.tools/blob/main/app/src/components/DetailedRelevantSkills.svelte

One difference here is the gradient, fading out the last visible items, and then button the shown on top.

Add fuzzy search to make it easy to find specific content

https://paullj.github.io/posts/fast-lightweight-fuzzy-search-using-fuse.js

• build search index at build time to improve performance.
• client side or server side
• Potential solution: https://github.com/metonym/svelte-typeahead

Update the URL based on selected filters on the explore page

Feature idea: Update the URL based on selected tags (and filters in general), with for example URLSearchParams. This should allow people to share a link to show all Methods or Courses for example.

Fun feature but there are more important things to do right now. Keeping it for the future though.

Update fonts to use Inter to align with new IDG branding

Update to new fonts:

• Generated SVG icon
• App font
• Follow web font best practices for 2022

Add app icons

check out if the web app manifest described in this guide has suggestions for good icon sizes:

https://web.dev/learn/pwa/

Add flexible yet minimalistic filtering options - tags or specific fields?

• Mapping tools to the SDGs
• Mapping tools and their relevancy to the IDGs
• Mapping tools and what kind of support they have - what level of scientific support (on a scale)
• Allow tools without scientific support, but that are promising. Just be clear that they need more research, and clearly separate them from the scientifically proven methods/tools.
• Tagging tools as Non-profit vs for-profit
• Tagging tools based on type: For example Method, Course, Exercise, Book, Workshop

For relevancy scores, we likely should use separate fields, like we do now for skills and categories, but instead of storing the ID we keep the ID + relevancy score. This would allow true sorting based on what is most relevant.

Some thoughts about implementation

By using tags, it would be flexible to add/update filtering options, and possible to use different presentation + featuring in the UI. The simplest form is an array of strings to represent tags

Tags could also be a bit more structured, by adding proper relationships. This would make it easy to categorize and explore the content in the CMS, as well as in the app. And not too much complexity.

By adding custom fields for every property of tools, it will add more complexity and custom code to maintain. Relationship-supported Tags will likely be the flexible yet minimalistic solution that we need.

UX: Open up all menus with currently selected skills to develop when clicking the link "Change skills here" from the /toolbox view.

Make the app a PWA that works offline

Guide: https://web.dev/learn/pwa/

Improve landing page and explain the project vision

• Explain why IDG.tools exists
• Explain how it works (3 simple steps)
  • Find tools and resources relevant to what you want to practice on (or start with a self-assessment). Filter on tags, skills, and for example self-directed vs facilitated practices.
  • Try the tools in practice
  • Give feedback directly on IDG.tools and co-create with the community to make the digital field kit even better.
  • Welcome to join the co-creation and make improvements. Anyone who stands behind the principles, processes and code of conduct is welcome to collaborate. Option to get involved in the various teams running the IDG community platform.
• Join a community and practice with others - maybe list IDG hubs?
• Highlight contributors - both GitHub and in the future also from the CMS
  • Idea: highlight contributors similar to how https://climatemind.org are doing it - personal, and with clear role descriptions of which skill set could add more value to the team. Would be hard to maintain, but looks great.
• Invite co-creators to join us on GitHub and Matrix to learn more and get involved.

Important:

• Clearly explain the process of how IDG.tools is co-created to include diverse perspectives.
• Explain the difference between scientific backing for methods and tools, compared to emerging and promising tools that need further research but are still included (though with clear separation) if they meet certain criteria.
• Define the criteria for how content is selected and featured. Explain that we don't have all the answers, and so we're keen to add more perspectives for others who want to contribute. We're developing as we go.

---

• filter on Time - help people get started right away and try something small

For who:

• We need to adapt to different target audiences
  • Individual
  • Leader/organization who want to practice with IDGs

Idea: Add a preview panel in the CMS to let the user preview their contribution during editing.

Idea: Add IDG self assessment so people can see which skills they need to practice

Potential issue: duplicated skill relevancy scores

Maybe this can be solved at build time - or with a CMS validator for that field.

Add links to community and GitHub on the IDG.tools website

UX: ensure the back arrow always navigates one level up, instead of following browser history

After some testing, it makes more sense that the back arrow navigates one level back in the app experience, e.g. from /explore/[link] to /explore and then to /

Variable background as you go deeper in the app

Decrease opacity of dark filter as you go deeper into the app/content, until you're only at 95% opacity

Re-enable redirects when sveltekit / vite issue has been resolved

See reference in /explore/[link]/+page.server.ts

Redesign to mirror 29k version

Update design as found in Figma

Add share button to open native sharing modal. Or copy the link to make it easy to share for desktop

navigator.share

Learn more at https://developer.mozilla.org/en-US/docs/Web/API/Web_Share_API

Not widely supported, but would be a nice progressive enhancement for users of Chrome on Android. For non-supported browsers, the share button could copy the link to the tool.

Add project README and describe how to contribute

• Consider changing the links to github discussions to be https://github.com/Greenheart/idg.tools/discussions/new?category=ideas where it's easier to understand how to contribute. Or even better, link to the contributing guidelines, or have a page about contributing on IDG.tools.

Inspiration: https://github.com/sveltejs/vite-plugin-svelte/blob/1ed3df1b9c53b02ae03dd546746d39b48a0ded89/CONTRIBUTING.md

Add GraphQL client to fetch data in the app

Or if we go for a static content approach, use another suitable solution.

Todo: Require special auth token to be able to access the GraphQL API.

Hide the back button from the mobile menu

This is only visible on non-root pages, for example /explore

Create seed data with IDGs and example tools

This will make it easy to get a local DB up and running.

Essentially take a backup and commit it to git

Or maybe even commit the sqlite db in full, though it won't play nicely with multiple contributors.

Add content build to the app build process

To ensure the CI/CD pipeline can catch content errors when previewing content, we should run the content build script as part of the general app build.

This will also allow us to preview the latest content changes, even for PRs where people haven't run the content build locally and committed the output. Basically needed to unlock the CMS editing experience we want.

TODO

• Update app build to include content build
• Remove old scripts and clean up build process (everything is version controlled and can be added back in the future if needed).

Add translations for all UI texts

Edit: This is not a top prio until we have the capacity to maintain the content in multiple languages. Although the tech is mostly in place with the CMS having support for new collections for example.

Implementation idea

Create a UI collection where we have translations for each screen.

Even if we only add English from the start, it would be nice to have support for full translations

Add IDG relevancy scores for remaining 29k content

Primarily focusing on these types of content:

• Exercises
• Meditations

Courses are already added. Tests and Challenges might be valuable, but don't feel like a top prio for me. Open to adding them anyways if someone think they should be 🙂

Add dynamic meta tags for each page of IDG.tools

This would make it easier to share links in chat apps and on social media. Important to make the content easier to share.

Generate an OG image to be used for the site. One for all pages is a good enough start.

This could be a good first time issue to contribute a meaningful improvement to the project. Let me know if you want help getting started 😄

Create about page with links and info

• Background and core team
• How to get involved in the community (link to IDG.community)
• How to contribute (link to specific page on IDG.community)

Add the IDG category color to each skill

Since one of the most common use cases requires us to find the color for a given skill, it would make sense to add the category's color to each skill at build time. This would make the app code simpler.

Show skill descriptions somewhere

The skill descriptions are valuable to help understand the framework.

Ome idea is to show the akill deacription when pressing a skill on /explore/[link], but that is not as obvious.

Need something better to deacribe the framework in full inside the app.

---

Idea: Show skill descriptions like the SDGs https://sdgs.un.org/goals#goals

Each category has their own colors, ans each skill is shown as a box with the name of the skill, with the description only visible on hover/touch.

Or to make it better adapted for mobile, create a nicely designed list. Perhaps sections that are animated to look more interesting.

Configure Netlify CMS for github integration

• Store content as JSON files in a /content sub-directory.
• Update the /cms sub directory to use Netlify CMS (with vite) and delete old code.
• Create the content structure based on current schema.
• Create an ID widget that creates unique ids for content created in the CMS.
• Enable relationships between content pieces.
• Add GitHub backend with open authoring - allowing people to sign in using their GitHub accounts, and create pull requests from their own forks.
• Maybe use GitHub GraphQL API for faster performance.
• Maybe support file uploads for images via a public directory. Or use embeds and links.

Make it possible to filter content on the explore page by tags

This would make the content easier to explore.

Implementation ideas

• Show a horizontal scrolling list of all tags on top of the explore page, similar to the new 29k discover screen.
• Selecting a tag on the top of the explore page should filter out the content that has that tag, and also matches other filters.