blindnet-io / blindnet.dev Goto Github PK

Use Docusaurus instead of mkdocs for a better look and feel by default, additional features (e.g. blog), and extensions possibilities.

Context

related DevRel actions are tracked in https://github.com/blindnet-io/devrel-planning/issues/14
follows experimentations by @noelmace and @m4rk055, and the associated meeting
replace https://github.com/blindnet-io/devrel-planning/issues/63

Timeframe

Start date: to be defined by @m4rk055
Due date: to be defined by @m4rk055

Steps

from https://github.com/blindnet-io/devrel-planning/issues/63#issuecomment-1080364433

• explore options for search (cf. https://docusaurus.io/community/resources#search)
• check if code blocks can be used inside admonitions, and other related features of mkdocs superfences
• rewrite inline code blocks if needed (cf. mkdocs inlinehilite
• rewrite footnotes if needed (cf. mkdocs footnotes)
• update lang-code in code blocks for syntax highlighting, and confirm all the languages we need (so far, JavaScript, Typescript, Node.js, C#, Scala, and PHP) and supported
• Release new Docusaurus docs to docs.blindnet.io

Make a thorough review of the existing docs and make sure they are clear enough from @noelmace perspective.

Set-up the blog feature in the Dev Portal.

Create CI/CD workflows (Github Actions) for the docs project.
yarn build and copy the content of the build folder to the hosting service.

Add minimum SEO and social network configuration and optimisation.

Partially depends on #7

Minimal Requirements

Not exhaustive at all, but it's a minimum we can start with. See the docs for more details.

• any page can have a coherent and attractive associated card when shared on Twitter (see Twitter Card Validator)
• most shared pages (starting with the home page) have predefined metadata
• we have an associated account for Google Search Console and the result looks OK

How to proceed

See https://docusaurus.io/docs/seo

Request by @Vuk-BN for 2022-07-22: Deliver a thorough plan describing the new structure of the website while progressively moving toward the DevKit.

Define the new structure and create the associated sections.

Inlude more information about the current version of the product, and less about how we operate.

Links are not standing out enough

Context

Before #16:

After #16:

Algolia DocSearch indexes documentation and provides a search component.
It's free for open-source projects.

Docusaurus has official support for DocSearch.

Currrently, blindnet.dev uses @easyops-cn/docusaurus-search-local for search which is decent but requires downloading the search index and is not as feature rich as DocSearch.

Add a new "community" section to list the most important information for the community :

• how to contribute
• openness framework
• follow us on Twitter
• join our Slack

This is only a copy past of what Milan previously wrote.
I'll update this later.

Originally posted by @noelmace in #50 (comment)

See also #50 (comment)

Write a new home page content to better introduce the dev portal and explain what it is.

Problem

Right now, calling an inexistent path on blindnet.dev lead to an Azure 404 page:

Proposed Solution

We need instead to correctly redirect to Docusaurus so its internal 404 page is shown instead:

How to conduct the change

I believe this is just something to configure in Azure Static Apps.

@m4rk055 let me know if you want to address this issue. Otherwise, I'd be happy to.

follow blindnet-io/openness-framework#33

In order to avoid duplication between READMEs, we need to write a new and more thorough "Contributing" doc based on what we established in the devkit-README template.

This new doc should be part of the yet-to-come "Community" section (see #14)

Adding https://giscus.app (or a similar solution) to connect Github Discussions with blindnet.dev.

• @noelmace confirm the budget for buying the blindnet.dev domain name with @Vuk-BN
• @noelmace confirm deadline & feasibility with @filipblnt
• buy blindnet.dev domain name
• move docs.blindnet.io to blindnet.dev
• make sure old URL are correctly redirected
• replace "blindnet-docs" and "dev portal" by "blindnet.dev" / ".dev" / "dev" / "develop" everywhere

On any other browser than Firefox, pictures on the home page are not rendered.

I tried to set height: 100% (bug reported here) directly on the svg element of the pictures and it seemed to fix the problem. Don't know if it breaks something else.

Add a section explaining in detail how extensions via "Term Dot Notation" exactly works, and how to use it.

Context

Based on @m4rk055 feedack:

I'll remove these mentions, and open an issue to discuss this more extensively then.
Thx for the feedback.

Originally posted by @noelmace in #50 (comment)