iotaledger/iota-wiki

IOTA Wiki

EXPLORE THE WIKI

Report Error · Request Topic

Table of Contents

• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Local Development
• Contributing
• Contact

About the Project

The IOTA Wiki is a central hub for entering into the IOTA ecosystem. A community driven initiative to provide an up-to-date collection of introductions and further reading about the technology, the teams, the community, and everything in between. So anyone can learn how to build, adopt, and engage with IOTA, all in one space.

Built With

The IOTA Wiki is built using TypeScript, ReactJS and Docusaurus v2.0.

Getting Started

Prerequisites

• git 1.8.2 or above.
• Node.js 16.10 or above.
• Modern Yarn enabled by running corepack enable.

Preview Locally

To preview the Wiki locally, use the following steps. For more detailed scripts, see Pre-configured scripts for reference.

Please note that the Wiki has a lot of content, so currently the initial build is taking a while. Effort is taken to try and reduce the build time in the future.

1. Clone the repository by running git clone https://github.com/iotaledger/iota-wiki.git and go to the directory with cd iota-wiki.
2. Install dependencies with yarn.
3. Prepare the environment by running yarn prepare, this has to be done only once.
4. Preview the Wiki with yarn start, this will start a development server serving the Wiki with hot reload capability, so it will update content after any changes were made.

Pre-configured scripts

Script	Explanation
prepare	Prepare the environment by checking out submodules build.
start	Start a development server serving the Wiki, with hot reloading on changes.
start:section:{section}	Start a development server serving only a section of the Wiki, with hot reloading on changes. Available sections are build, get-started, learn, and maintain.
build	Build the Wiki. To build for production, checkout the latest version of external documentation by running yarn checkout:remote and set the MODE environment variable to production.
checkout:remote	Check out the latest version of external documentation.
generate:api	Generate available API documentation configured through the Docusaurus OpenAPI plugin and by compiling documentation from source code.

Contributing

The IOTA Wiki is maintained by the IF and community contributions are always welcome. The DX team and related teams from the IF will review all issues and pull requests posted to this repository. If you notice any mistakes, or feel something is missing, feel free to create an issue to discuss with the team or directly create a pull request with suggestions. Here is a basic workflow to open a pull request:

1. Fork this repository to your own account and clone it (git clone https://github.com/<YOUR_USERNAME>/iota-wiki.git)
2. Create a feature branch for your changes (git checkout -b feat/amazing-feature).
3. Make your changes and optionally preview them locally.
4. Run yarn format and yarn lint and fix any remaining errors and warnings.
5. Commit your changes (git commit -m 'Add some amazing feature').
6. Push your changes to your fork (git push origin feat/amazing-feature).
7. Open a pull request to the main branch of this repository.

Have a look at CONTRIBUTING for further guidance.

Versioning

To find out how to version your docs, read this guide.

Online one-click setup for contributing

You can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click it will prepare everything you need to build and contribute to the Wiki. Just click on this button and skip step 1 from above.

Contact

Phylo - Phyloiota - Phylo [Community DAO - lets go!]#2233
Jeroen van den Hout - jlvandenhout - jvdhout#4402
Dr.Electron - Dr-Electron - Dr.Electron#9370
Critical - kilianhln - Critical#7111
JSto - JSto91 - JSto#3746

iota-wiki's Issues

Write Content for: USE/Smart Contract/Programable Contracts

USE/Smart Contract/Programable Contracts

Create dev branch

Setup a dev branch for main pull requests and testing.

Write Content for: LEARN/Wallets/Firefly Wallet

Write Content for: Learn/About IOTA/Data Transfer

LEARN/About IOTA/Data Transfer

Update footer menu

Rewrite footer menus for the new categories. Using main as headers and sub categories as menu items.

Subcategories items to link to the top page in each of the respective subcategory menus in the sidebar.js file

Add all selected and used content and links of a "doc" content page into the corresponding folder in "doc ref" as a source.

Also work in progress of the content team...

Add wiki docs assets folder

Maybe we should create an assets folder for storing all 'in wiki' assets. It would be primarily for storing images, but also sub-folders for other content such as pdfs or other assets we may need in the future. It would also make it easier for contributors to add their assets if they need to as well.

Implement an in-page rich text editor for non-dev contributions.

To allow a greater audience to contribute, the idea is to have an in-page editor that does not require any knowledge of markup languages or git, but transparently translates edited content to Markdown and integrates well with our current GitHub workflows.

Ideally the frontend has the rich text editor look and feel like Google Docs or Word. There are a few open questions:

• Do we want to be able to save our progress locally, to continue at a later time?
• Do we want to allow editing multiple files at the same time? A topic might live at different locations in different forms. Topics might be interrelated.
• If so, how do we present these files? Using tabs in the page or utilize browser tabs?
• Do we want contributors to identify themselves, for example to track contributions and to be able to notify them about requests for updates or changes before their changes are accepted?

Content contribution guide:

Explain the content strategy/philosophy, so the contributors know how we want the content to be provided. Implement an explanation for the in-page editor.

Write Content for: LEARN/Networks/IOTA 1.5 - Chrysalis

LEARN/Networks/IOTA 1.5 - Chrysalis

Update design of the links in the content pages

It would be great if we could style the links of the content pages. Currently, we can't, since when we try to style the links of the content page, this styling gets applied to all the links on the page. Maybe the content page links need their own class?

Planned design: https://www.figma.com/file/rmb5zuItKmZH8OflJYnhSc/IOTA-wiki?node-id=1133%3A2482

Write Content for: PARTICIPATE/Support the Network/Run a Node

PARTICIPATE/Support the Network/Run a Node

Write Content for: /LEARN/About IOTA/Value Transfer

LEARN/About IOTA/Value Transfer

Navigation through the wiki.

Currently, we imagine the wiki being split into five sections: LEARN, BUILD, PARTICIPATE, PRODUCTS, RESEARCH. BUILD/Developer Docs could easily include a dozen software projects that have a dozen articles each. In total, the wiki would consist of dozens of subsections and hundreds of articles. That's a lot to navigate through.

My suggestion would be to have top-level sections listed in the topbar like the programming language picker in wc3schools. The user would switch between top-level sections by clicking on topbar. The sidebar would list TOC only of the current top-level section, but not the others.

This solution would split advanced developer's docu (BUILD section) from end user docu (all other sections). Having the rest four sections separated from each other in the same way means consistent UI as five buttons in the topbar would all do the same. It also reflects the structure: if we have "devs vs non-devs" switch, it would essentially bring a new layer to our document structure: DEV that only has BUILD section, and NON-DEV that has the other four.

Finally, I think this is not just about "dev vs non-dev". With RESEARCH section, it is also "academic vs non-academic", and with PARTICIPATE section, it is "engaged user vs casual user". I do not see that we need to separate docs for devs more than docs for any other major user group.

Write Content for: USE/Utilities/Tangle Explorer

USE/Utilities/Tangle Explorer

Update Fonts and fix main text color

Font Style of Side nav
Inter for subheaders (not metropolis)

Font Color:
Body text should be white/black and the secondary text a bit greyer/lighter (inversion from how it currently is).

Continue content for LEARN/Networks/DevNets

LEARN/Networks/DevNets

Rate content links into categories of complexity - simple, for developers, complex high level to deliver users a choice tailored to their needs

Gonna work on a basic structure of the link content to have it categorised in: simple ELI5 style / experienced - dev style / high level - science style.
Hope we can get some input also from UX if this approach suits and what would be the best way to deliver that

Hide the assets folder in sidebar

The new assets folder is visible in the main wiki sidebar menu, need to figure out a way to hide it from auto generatiing in the docosaurus sidebar.

Show the current state of created pages in an Overview in the Readme and keep it up to date

ill update the png whenever new content gets picked up

Replace dropdown lists with mega menus

The ground we are covering with the Wiki is vast and listing all kinds of different topics in standard dropdown menus to navigate them is starting to get confusing for readers.

To allow us to categorize and group these topics more clearly, we've opted for a mega menu component containing a grid like layout, instead of using linear dropdown lists.

The mega menu dropdown should probably have the following design features:

• The menu should be responsive just like standard dropdowns are currently. On desktop it will expand all categories and layout all items in a grid like layout. On mobile it will turn into a linear list of items with collapsing categories.
• The menu layout should consist of columns.
• Each column contains one or more items and/or categories.
• Each category contains multiple items.
• Items have a label and optionally a sublabel and/or an icon.
• The menu should be configurable from the Docusaurus configuration file.

Write Content for: LEARN/Wallets/What is a Wallet?

LEARN/Wallets/What is a Wallet?

Write Content for:DEVELOP/Getting Started/Send a First Message

DEVELOP/Getting Started/Send a First Message

Continue content for USE/Use cases/Digital Assets

USE/Use cases/Digital Assets

Add a topics page where content is listed by topic.

As discussed a separate page to navigate content by topic would be a great addition. This would also allow to implement "popular topics" in the landing page header more easily as this would just link to the specific topic in the topics page.

The idea is to use the keywords of the frontmatter to automatically index topics during build and fill the topic page with cards for each topic, containing links to the content related to that topic.

The popular topics section on the landing page can be implemented as a React component which is configurable from the Docusaurus config file. So initially we can configure the popular topics manually. At a later stage we could look into how to automate this.

Proposal for the Readme.md

General

• Link to Live Wiki Page
• Ask designer for a cool hero image.

Contributions:

• Link Discord with channel name
• List core maintainers (with GitHub and Discord name)

Misc

And a general question for the wiki team - is there a plan to also extend the wikipedia.org pages?
For example:

• https://en.wikipedia.org/wiki/IOTA_(technology)
• https://en.wikipedia.org/wiki/Tangle

Thanks for doing this! ❤️

Blog posts always display one min read

In the Blog section, I think posts are always being automatically labelled as "One min read" because we're using excerpts but the wiki thinks they're full posts. Perhaps we should remove the estimate, given that it's always gonna show 1 min. Thoughts?

Sidebar menus and Dev Docs Integrations.

The discussion is how best to implement the developer documents into the wiki without overwhelming the sidebar navigation.

The core sidebar menu represents the low-level content for the wiki to include introductions, outline, features, basic guides, and other information. Within these pages in-page links and additional resource links can be added to guide the user to more high level content.

The issue we have is the amount of developer documentation is substantial enough that to include it in the current sidebar would present a navigation nightmare.

Suggestions

It has been suggested to keep the current sidebar as is, but to add a top bar/tab function that can enable a second sidebar which will contain a high level menu that can guide users through developer documentation, repos, and more tech heavy content.

This menu would utilise developer documentation in their current state, pulling them from their respective repos

Active State not working correctly

Describe the bug
This is the normal Menu, without an active state:

If i click on a page, there should be just one menuitem selected with primary color, this is how it looks now:

Expected behavior
Just the current menu item should have an active tag.

Navbar element gets unhighlighted once clicking somewhere on the side nav

Continue writing Content for: LEARN/IOTA Token/Buying IOTA

LEARN/IOTA Token/Buying IOTA

Write Content for:LEARN/Resource materials/Glossary

LEARN/Resource materials/Glossary

Research content links and resources

Started working on that already. Link archives pages can be found in the "docs-ref" section. Continue to collect links to original content, IF blogs, IF releases, Tech - updates, IF websites, IF Docs, IF - Githubs, IF Youtube content, HelloIota video content, helloIota blogs...

Write Content for: LEARN/About IOTA/Why is IOTA Feeless?

LEARN/About IOTA/Why is IOTA Feeless?

Write Content for: PARTICIPATE/The Community/Social Media

PARTICIPATE/The Community/Social Media

Write Content for:USE/Use cases/Data Confidence

USE/Use cases/Data Confidence

create the content of the pages. Content taken from available sources combined and streamlined as an topic overview approach. that describes the topic broadly but also answers the most important things already. Add linking to external sources to dive deeper into the topic

Adam and myself will start on that step by step. Trying to use available source content and kind of extract the best possible overview. Find a suitable language approach that is not to complicated but exact enough to deliver information on point.

Continue writing Content for: LEARN/About IOTA/Roadmap to Decentralization

LEARN/About IOTA/Roadmap to Decentralization

Write Content for: LEARN/About IOTA/An Introduction to IOTA

LEARN/About IOTA/An Introduction to IOTA

Write Content for: DEVELOP/Exchange Integration/Guide

DEVELOP/Exchange Integration/Guide

add a content template on all content pages

Restructure docs

May be worth moving our test and reference materials to a new folder called docs-ref and keeping the main docs folder clean as this is the primary reference folder for docosaurus to populate the wiki.

Write Content for: LEARN/About IOTA/Energy efficiency

LEARN/About IOTA/Energy efficiency

Write Content for: PARTICIPATE/Support the Network/Run a Node

PARTICIPATE/Support the Network/Run a Node

Add new topic eco-system to community section of wiki

Describe the solution you'd like
I would like a section to be added that gives an introduction to the community eco-system in the IOTA wiki section community

Additional context
To provide an overview of the IF supported community developments that exist within the IOTA ecosystem.

Update to new nav bar & integrate sidebar.js menus

Is your feature request related to a problem? Please describe.
We are still displaying old menu items and navbar menu items.

Describe the solution you'd like
Update to new navbar items and implement new sidebar menus for the individual sections:
LEARN, USE, PARTICIPATE, DEVELOP

Write Content for: USE/Utilities/IOTA IPFS

USE/Utilities/IOTA IPFS

When reloading the page in light mode, the dark mode globe gets displayed

It should be the light mode globe that gets displayed.

Write Content for: USE/Utilities/Visualizer

USE/Utilities/Visualizer

Add support for Mathjax

Is your feature request related to a problem? Please describe.
In order to describe mathematical problems (especially in reserach posts and specifications), the wiki needs support for math notation.

Describe the solution you'd like
Mathjax

Describe alternatives you've considered
Briefly described in the linked issue from Docusaurus

Additional context
There has been previous discussion about this topic at Docusaurus with a few solutions assessed and a working solution seemingly identified:
facebook/docusaurus#2078