What should be done before deactivating the old mediawiki?

[dpolivaev]

The old mediawiki is not good enough, but it still has a landing home page with information for newcomers, and it has categories grouping pages so that people have a chance of finding relevant content.

Now the content is migrated, and I would like to ask you how the home page should change and if we need any replacement for category pages before freeplane.org can be linked with the new content.

Also I am not sure if linking to the "old wiki" content from the top of every page is needed and which more descriptive name we can give this content. "Old wiki" seems to be a term only a few people knowing its history can understand.

Any ideas are appreciated.

[macmarrum]

My proposal

• Old wiki → Pre-2021 wiki
• New wiki → Post-2021 wiki

Regarding categories, a static page could be added listing the migrated pages grouped by category.

The landing page could, for now, remain the same, i.e. https://freeplane.github.io/wiki/migrated-from-mediawiki/#/Home

But first, I would propose that people perform some verification of the migrated pages to decide if the migration/conversion from MediaWiki to Markdown is good enough, and report here any major issues.

What I have in mind is that there might be some additional work needed before linking to GitHub instead of MediaWiki, e.g. identifying and extracting missing media files, especially mind maps, and linking them in the migrated pages.
Alternatively, each page migrated from MediaWiki could have a link to the original page, so it could be easily viewed, if needed.

[dpolivaev]

@macmarrum Could we have a call to talk about the migration process? What times/days work better for you?

[macmarrum]

@dpolivaev sure thing. I'm on Discord: macmarrum#3214. Let's continue there.

[sifran-github]

@macmarrum Could we have a call to talk about the migration process? What times/days work better for you?

i would like to join as well.
next week sometime? during day time in europe?

[macmarrum]

Here are the main points that Dimitry and Mac discussed last night

Dimitry proposed

• to focus only on several pages to be migrated from MediaWiki to GitHub
  • Command-line_options_and_configuration.md
  • Add-ons_(install).md
  • Conditional_node_styles.md
  • LaTeX_in_Freeplane.md
  • Relationship_to_FreeMind.md
  • Spell_checker.md
  • Translation_How-To.md
  • Contributing_to_Freeplane's_Development.md
  • Scripting.md
  • Scripting!_Script_filter.md
  • Scripts_collection.md
  • Scripting!_Jython.md
  • Scripting_environment_setup.md
  • Export_Using_XSLT.md
  • Add-ons_(Develop).md
  • Git_howto.md
  • How_to_build_Freeplane.md
  • IDE_setup.md
  • Plugin_development.md
  • Mind_map_gallery.md (low priority)
• for the pages to be integrated into the new wiki
• to rename some of the new-wiki pages
• to use an Attic where draft pages will live until they are ready to be moved to the main wiki
• to put a concrete hierarchy of pages in the sidebar (3 levels), with level 1 as:
  • Home
  • Getting started
  • How to get help
  • User documentation
  • Mind map examples
  • Contribute
  • Scripting
  • Coding
  • Attic
• to decide which home-page content should be used → Mac and Dimitry settled for the repo README.md with features-rundown images by Rexel
• to rename the project from wiki → Mac and Dimitry agreed on docs

Mac will work to implement the changes. Mind_map_gallery.md is the most tricky one and will require the most work to save the mindmap files and images to disk and structure them nicely in Markdown. Anyone wishing to help is welcome.

[dpolivaev]

Thanks for the session and for the summary. After reading your post I would like to come up with the following suggestion about the mind map examples: I suggest removing them from the documentation entirely. I would keep only the mind maps eventually needed as an essential part of the documentation.

In the past, the embedding of interactive Freeplane mind maps in web pages using flash or Java Applets was possible, but now both technologies are no longer supported by the browsers. It means that we can make available only images, videos, pdfs, or mind map files for download. Because GitHub discussion forums would allow everyone to share their mind maps in any possible format I think it is the easier and better way to go. Currently, in https://github.com/freeplane/freeplane/discussions we already have a category called "Show and tell", but I could also add a dedicated category called "Shared mind maps". I have just added it.

So I think that the migration of example mind maps is not a part of the media wiki migration but a separate activity and that they do not need to become a part of the freeplane documentation project.

[dpolivaev]

The new category looks like that:

[dpolivaev]

Oh, I found that it already has got content freeplane/freeplane#254

[dpolivaev]

So we could just link the docs to https://github.com/freeplane/freeplane/discussions/categories/shared-mind-maps

[macmarrum]

Sure thing. I like the idea 👍

[sifran-github]

I did post an initial scripting documentation pull request, #20, but i understand and support the choice not to merge it yet, because the old wiki just has much more information.

Is it possible that we schedule a discord talk about the documentation?

I need some help regarding changes i want to make. i'm not sure about:

1. What scripting documentation do we currently have?
2. How to write a new wiki? (if it is using forks and pull requests: then i think that i understand this point).
3. How to mark what i have done? mark/remove from the old wiki.... so lets say that i want to rearrange the current scripting documentation into new categories, and it will take a few weeks of work, and i want to mark which pages in the old wiki i have already converted... - how to do so?

My confusion is mainly about the status of the old wiki, and how to build the process of converting/changing it.

[macmarrum]

@sifran-github

This is what I can answer already now:

1. Please have a look at the preview of the target site (after the changes were introduced) https://macmarrum.github.io/freeplane-docs/
2. Yes, using forks and pull requests is fine
3. The old wiki is basically gone. Dimitry proposed to keep only selected pages. Please see the comment above

[sifran-github]

Hello @macmarrum

Dimitry and I are thinking about coordination of the freeplane docs project. We think that use of the main repository https://github.com/freeplane/docs could be easier for synchronization. if you have made changes to your local repository, wouldn't it be better to push it to freeplane/docs (either to main branch or to some other branch)? then we can pull it, edit it and add on top of your changes?

[sifran-github]

@macmarrum After talking to dimitry, I want to talk to you about the documentation. lets try to meet in discord, and schedule it?

[macmarrum]

Sifran, Dimitry and Mac discussed the topic again.

Dimitry explained that he had meant to have all pages migrated from MediaWiki, not only the ones listed in the previous post, and for them to end up in the Attic; the selected pages to be the priority for merging into docs.

Therefore Mac will rename migrated-from-mediawiki to attic – it contains imperfect pages. Sifran will write instructions about how people can join in: to review the attic pages, correct them, enhance and integrate into docs.

Here's the initial structure, including the priority pages:

* [Home](/)
* [Getting started](getting-started.md)
  * [Command-line options and configuration](Command-line_options_and_configuration.md)
  * [Extend with add-ons](Add-ons_(install).md)
* [How to get help](how-to-get-help.md)
* [User documentation](user-documentation.md)
  * [First steps](first-steps.md)
  * [Working with mindmap files](working-w-mindmap-files.md)
  * [Formatting maps and nodes](formatting-maps-and-nodes.md)
  * [Styles](styles.md)
  * [Templates](templates.md)
  * [CSS for HTML/Markdown](css-for-html-or-markdown.md)
  * [Conditional node styles](Conditional_node_styles.md)
  * [LaTeX in Freeplane](LaTeX_in_Freeplane.md)
  * [Relationship to FreeMind](Relationship_to_FreeMind.md)
  * [Spell checker](Spell_checker.md)
  * References to other known documentation/tutorial sites
* [Mind map examples](https://github.com/freeplane/freeplane/discussions/categories/shared-mind-maps)
* [Contribute](contribute.md)
  * [Translation How-To](Translation_How-To.md)
  * [Contributing to Freeplane's Development](Contributing_to_Freeplane's_Development.md)
* [Scripting](Scripting.md)
  * Formulas
    * [Formulas](Formulas.md)
    * [Formula filter](Scripting!_Script_filter.md)
  * Scripts
    * [Scripts collection](Scripts_collection.md)
    * [Scripting! Jython](Scripting!_Jython.md)
    * [Scripting environment setup](Scripting_environment_setup.md)
  * XSLT for export/import
    * [Export Using XSLT](Export_Using_XSLT.md)
  * Add-ons
    * [Add-ons (Develop)](Add-ons_(Develop).md)
* Coding
  * [Git howto](Git_howto.md)
  * [How to build Freeplane](How_to_build_Freeplane.md)
  * [IDE setup](IDE_setup.md)
  * [Plugin development](Plugin_development.md)
* Attic (draft documents) <!-- as a separate docsify? -->
  * [Old home](old-Home.md)
  * [Many unsorted ideas related to Freeplane](many-unsorted-ideas-related-to-freeplane.md)
  * [Understand the Freeplane interface](understanding-interface.md)
  * [Understanding nodes](understanding-nodes.md)
  * [Customizing Freeplane](customizing-freeplane.md)
  * [Tutorials](/tutorials/index.md

Mac explained about docsify sidebar and sub-level sidebars. Dimitry was for introducing this concept, to make sure the side bar is short.

[macmarrum]

The site is reorganized as agreed → #28

[dpolivaev]

Is it ready to replace the MediaWiki as freeplane.org home?

[macmarrum]

I vote it's ready 😄
What do you think?

[sifran-github]

I want to emphasis that Attic is NOT a snapshot of the old wiki, and should contain pages that are NOT YET in the main branch. It is a work in progress. When we take a page, improve it and put it in the new wiki, we should delete it from the attic.

So:

• in the future, If someone wants to see WHAT PAGES WERE IN THE OLD WIKI BUT ARE STILL NOT REFLECTED IN THE NEW DOCUMENTATION, he can look at the attic. Hopefully over time it will be empty.
• in the future, if someone wants to see HOW THE OLD WIKI LOOKED LIKE, he can watch the old wiki, or if it is turned off, he can watch old versions of github somehow (some way to view a snapshot of the old wiki).

that's an important distinction on the purpose of the attic.

[macmarrum]

If you edit the doc MD files locally in VS code you can easily find and replace all links when the file is moved or renamed. The proxy files in the attic are basically semantic noize.

Given the proposed set-up — attic being a separate docsify site — it might be less straight-forward than you expect. But might be feasible. It's fine with me to try the move-and-re-link approach.

[dpolivaev]

Given the proposed set-up — attic being a separate docsify site

Given context-dependent sidebars we could probably also include the attic as a usual first-level chapter.

[dpolivaev]

I mean I don' know what is better and think both is reasonable

[macmarrum]

I want search results to be specific to the area: either docs or attic, but not both at the same time.
attic is its own docsify site to keep it segregated from docs

[ofossum]

Why don't we use the project-boards of GitHub to track which site has been transferred from the attic to the new wiki?
It would be a Kanban (which can also be automated) to keep visible cards, every contributor is able to see and we can move around, depending on the status of a given page (or which moves automated).

See this introduction to this feature of GitHub for example: https://www.youtube.com/watch?v=idZyqNIrt84

[dpolivaev]

The new documentation site is available at https://docs.freeplane.org/

[macmarrum]

Cool 👍

I can see that https://freeplane.github.io/docs/ redirects to https://docs.freeplane.org/

It's worth to note that Attic is broken. The implemented approach depends on the Docs site being located at /docs/ and the Attic site at /docs/attic/.

I will work on a fix.

[macmarrum]

Path are now fixed (PR #29). The browser cache might need to be refreshed for the new content in pages to load correctly.

[dpolivaev]

I added https://docsify-darklight-theme.boopathikumar.me/#/installation directly to the main branch.
How do you like it?

[dpolivaev]

I am trying to get the process right, so I forked the repo. Unfortunately, neither the link to attic works neither on your preview site https://macmarrum.github.io/freeplane-docs/#/ nor on my preview site https://dpolivaev.github.io/freeplane-docs/#/
Going to https://macmarrum.github.io/attic/ shows error 404.

Do you have an idea what happens and how it could be fixed?

[dpolivaev]

Finally, I discovered the missing pages under https://macmarrum.github.io/freeplane-docs/attic/#/ and https://dpolivaev.github.io/freeplane-docs/attic/#/

There is good news: in the version deployed on https://dpolivaev.github.io/freeplane-docs/attic/#/ switching the theme from light to dark has an effect also on https://dpolivaev.github.io/freeplane-docs and vice versa

[dpolivaev]

I could fix the fonts and opened a PR #32
Could you please check it at https://dpolivaev.github.io/freeplane-docs/#/ and https://dpolivaev.github.io/freeplane-docs/attic/#/ and merge it?

I still do not understand why the link to the attic does not work on our forks

@macmarrum

[macmarrum]

@dpolivaev Thanks. I've had a look; I'll create a PR against your repo with a few changes.

The link to Attic in the sidebar is static and absolute. It correctly points to Attic when the site sits in the root /, but fails when it's located in a directory e.g. /freeplane-docs/.
When doing a preview, we'll need to keep in mind the the link won't work. It needs to be entered manually in the location bar, e.g. /freeplane-docs/attic/, like you did.

[macmarrum]

Here's the PR with my proposed changes: dpolivaev#1

[dpolivaev]

Currently, https://freeplane.org still redirects to the old wiki page at https://www.freeplane.org/wiki/index.php/Home

Do you think it should redirect to docs.freeplane.org instead?
What should happen with the https://www.freeplane.org/wiki/index.php/Home? Keep it, hide it or change its subdomain?

[dpolivaev]

What do you think about having a discord call for better understanding?

[macmarrum]

I meant old mediawiki pages.

If you want to have the old wiki available for some reasons I would at least change the URL so that people can find it at a different place but all old links are consistently redirected to the new site.

Sounds good to me 👍

OK for a discord call, though I think all is clear now.

[dpolivaev]

I am in favor of the discord call. I am available now.

[dpolivaev]

If you can not make it now please let me know when you can.

[macmarrum]

I'm back. Now is fine for me

[dpolivaev]

Currently, page docs.freeplane.org does not reference its GitHub repository. Why not?
I think that it is kind of standard for the docsify rendered pages which makes the source markdown transparent and contributions a bit easier.

What do you think about restoring the link to the repository?

[macmarrum]

A good catch 👍 Given the agreed practice (fork - PR - merge), the "cat triangle" will be useful 😻

But only for docs, not attic – would you agree?

If no objections, I'll introduce this small change directly.

[dpolivaev]

Why not for the attic too?
I am even not sure whether attic should become searchable, but it is a different question

[macmarrum]

To me the objective of the "cat triangle" is for people to have an instant link to the corresponding repository so that they can contribute.

Docs is the target site for contributions. I would reject any PR to change a page in Attic except for moving it to Docs and relinking other pages. This kind of activity will be done by people knowledgeable about the process, i.e. those who already know where the Attic repository is located.

I would like to learn about your rationale for displaying the triangle in Attic.

[dpolivaev]

I think we have still a bit different understanding of the function of the attic.
For me, the content in the attic is not obsolete. It has just not been finished or ported yet.
I think it makes sense to have it discoverable and allow PRs to the attic for all work-in-progress pages.
I also think that the obsolete pages can be removed unless you want to keep them just for having valid targets for old links.

[macmarrum]

I think it makes sense to have it discoverable and allow PRs to the attic for all work-in-progress pages.

I see now what you mean. Fine with me. I can move the Attic pages to Docs, which will make them searchable. I'll work on retaining the banner, which might need some hacking.

[dpolivaev]

Hi @macmarrum, it seems that for me removing the redirect pages and fixing the links becomes easier after you integrate the attic with the other docs because of the differences how the links are currently handled in our forks and at the main site. So please go ahead and let me known when you are done.

[dpolivaev]

I created a PR fixing the navigation from my fork into your devel branch.
The decision to create a dedicated attic/Home.md is intentional.

If you are fine with it please merge everything to the main repo, otherwise comment.

[macmarrum]

Thanks. Good ideas in the first commit.

I added some more changes to make it consistent with Docs

• lowercase file names
• indented bullets for directory items

Please review PR #35

[dpolivaev]

I agree that in the solution my second commit was not consistent with the layout in the main section.
We actually have a choice between the solution from PR #35 and applying the logic from the second commit to the sidebars in the home.
The approach in my second commit is probably more generic because it works with any number of sections with many subsections. It also has an advantage that the upper-level sections always keep their positions.

Which solution do you actually like more and why?

[macmarrum]

I like the way Docs sidebar directory items unfold, showing subitems.
This is like in a filesystem tree.
The approach is quite flexible. It supports several levels, as can be seen in scripting

[dpolivaev]

Thanks, merged

[sifran-github]

i get errors trying to fetch the latest version to my local repository.
when i try to get it... i get the error message "This branch has conflicts that must be resolved".
i think that i need to use the command line interface in order to solve it somehow, but i'm not used to github.

[macmarrum]

That's to be expected. The structure of docs has changed. You will need to incorporate upstream changes to your fork/local first.

I would recommend learning a bit more about Git and GitHub before you continue. Maybe the following articles could give you a good start:

• https://www.freecodecamp.org/news/git-and-github-for-beginners/
• https://reflectoring.io/github-fork-and-pull/

There's a ton of other free tutorials and paid courses on the web for you to choose from.

Git is a standard nowadays. You will benefit form learning how to operate it.

Once you're comfortable with Git, if you still have trouble moving forward with freeplane/docs, let me know and we can dive into details of what you're trying to do and where you got stuck.

[dpolivaev]

I configured all redirects and a favicon.
Now, https://freeplane.org and https://www.freeplane.org are redirected to https://docs.freeplane.org.
Old wiki URLs are redirected https://docs.freeplane.org/#/after-redirect containing further instructions.

[macmarrum]

Excellent! 🍾 🎊

[dpolivaev]

I would like to disable the table-of-content insertions on many pages in the new docs but I could not figure out how to do it.

[macmarrum]

Docsify solves a similar problem when it creates a sidebar automatically.

Please turn it on locally starting with subMaxLevel: 6, and see for yourself.
It doesn't play nice with the page tree we have in the sidebar.
The mixing of pages and anchors is confusing, in my opinion. That's why I opted for my own implementation.

I am not sure if per-page opt-in or opt-out is better. If on your opinion the most pages should have the TOC, opt-out could make more sense.

I am actually leaning towards option 3, i.e. on top of the current way of injecting TOC to each page.

[dpolivaev]

I would like to have an additional opt-out maybe with combination with option 3.
As I created the https://docs.freeplane.org/#/after-redirect page it started with a heading, but I had to remove the heading just because I could not get rid of the TOC.

[macmarrum]

Fine with me. Please go ahead.
Alternatively, let me know to go ahead with the implementation.

[dpolivaev]

Alternatively, let me know to go ahead with the implementation.

Yes, sure, go ahead. Many thanks.

[macmarrum]

Implemented – PR #39
Preview: https://macmarrum.github.io/freeplane-docs/#/after-redirect
I took the liberty to rephrase after-redirect and rename the directory to align it with the new description.
Please have a look.

[1-DimensionalBox]

What fantastic progress with the documentation since our last community conference (28 May 2022)! Thank you 🙏

[1-DimensionalBox]

A more practical comment: as redirection and favicon were fixed by dpolivaev, I think we can close this topic. It would be clearer if discussions about Table of Content (TOC) management and the attic concept would get their own GH issue or GH discussion. Or do you think this is not necessary?