[Docs/Wiki][Enhancement] Migrate Wiki to github pages deployed by docfx?

[DevTKSS]

Proposal: Migrate Documentation to docfx for Improved Maintainability

Referring to issue #826, where it was mentioned that the co-maintainers currently cannot update or push changes to the Wiki, I would like to propose migrating the Mapster documentation to a docfx-based workflow.

GitHub Wikis often introduce limitations for collaborative maintenance, including the lack of a pull request workflow, limited review capabilities, and no CI integration. A docfx setup would address these aspects and align Mapster with many other .NET projects that use docfx for structured and maintainable documentation.

Benefits of a docfx-based setup

• Full pull request workflow for documentation changes
• Better maintainability and transparency for contributors
• CI-based documentation generation
• Option to publish a GitHub Pages site
• Familiar structure aligned with the .NET ecosystem

Reference Implementation

I have implemented a similar solution in one of my own repositories with community tutorials and Uno Platform learning content: https://github.com/DevTKSS/DevTKSS.Uno.SampleApps

This setup includes GitHub Actions workflows for building and publishing docfx documentation, which could be adapted for Mapster.

Offer to Contribute

If this proposal is of interest, I would be happy to prepare a pull request that introduces:

• docs/ folder with an initial docfx structure
• GitHub Actions workflow for generating and publishing documentation
• optional GitHub Pages deployment

Thank you for considering this suggestion.

[stagep]

This sounds like a great idea. The primary reason I didn't contribute to the documentation was the limitations that you mention. Would you take the current readme.md and use this as the docs/index.md?

[DevTKSS]

@stagep I am using the Readme of my Repo as Landing Page, you mean that? 🙃 Took me a while to came to the trick for sourcing the images for this file correctly (https://raw.githubusercontent.com Prefix), but now it works 😁

[stagep]

I just meant that we start with the content that we already have rather than nothing. I know nothing about docfx but it sounds better than what Github offers so I am on board. Thanks for bringing some new energy to this repo.

[DocSvartz]

@stagep The current wiki can be cloned to your computer. The only problem is that the repository appears to be corrupted. I wouldn't want to start from scratch. :)

[DevTKSS]

@DocSvartz What do you mean by "Corrupted"?

[DocSvartz]

[DevTKSS]

@DocSvartz VS2026 or VS Code? VS2026 is since I installed it half of the time playing hide and seek with gpg on my computer. VS Code then "just" works 🤷 but intellisense in VS202* is better then in VS Code when it comes to Xaml 😅

maybe you want to do a git rebase -i or remove and set your remote origins again 🤔 that would be what I would try if git has its five minutes 👍

PS C:\Users\Sonja\source\repos\Mapster> git status
On branch development
Your branch is up to date with 'mapster-origin/development'.

nothing to commit, working tree clean
PS C:\Users\Sonja\source\repos\Mapster> 

[DocSvartz]

VS2026.
I'm not talking about the mapster repository. I meant the repository in which the Wiki is located. https://github.com/MapsterMapper/Mapster.wiki.git

The specified git restore seemed to help and the files appeared.

[DevTKSS]

You see you know more about wiki and I maybe more about docfx 👍 Great addition!

[stagep]

If I understand correctly, the concept is to use docfx to create the .md files and we will use the current .md files and the Wiki content for the initial docfx content. This content will then generate .md files and the Wiki would be turned off.

I was unable to use https://github.com/MapsterMapper/Mapster.wiki.git in VS2026 but I was able to use it in VS Code but all I see are 38 pending changes and no files. @DocSvartz when you said "The specified git restore seemed to help and the files appeared.", what did you mean?

[DocSvartz]

I meant was that 38 .md files appeared in the directory where I cloned the wiki. :) I haven't checked if they match the files displayed. But it seems like one file is missing.

recovery command:

git restore --source=HEAD :/

This file is missing: https://github.com/MapsterMapper/Mapster/wiki/Mapping-Configuration-With-%22IMapFrom%22-Interface

And as far as I understood from the git report, its addition caused a malfunction in the repository.

[DocSvartz]

@stagep @DevTKSS I meant that you wouldn't have to start docfx content from scratch.

[DevTKSS]

@stagep

I was unable to use https://github.com/MapsterMapper/Mapster.wiki.git in VS2026

🤔 so I think git is sometimes a bit of a comedian🤣 I do get this fail too, the gotten repo seems to be empty, but checking out the git source control in vs code it still shows them, even the one thats marked in this output you showed. so I would be hopefull that it's possible to restore them 👍 you said 38 files?

You have a great memory! On Point!👍

[stagep]

That is what I got the first time I tried. Now I have the following:

[stagep]

There are 37 .md files in Explorer and Source Control has 38 untracked entries and 1 Index Deleted entry. So the 37 .md files = the 37 untracked entries in Source Control and the contents of the 1 Deleted entry can be copied and added as a file to make 38 .md files. I believe that putting "" in the name of Mapping-Configuration-With-IMapFrom-Interface.md caused the invalid path issue which made the repo seem corrupted.

[DevTKSS]

@stagep Yes except from that one file which I needed to copy from editor I will:

• [x] try to unstage + restore them / copy from editor
• [x] copy the markdown file over to the new location in the normal Mapster repo
• [x] sort them in their appropriate folder
• [x] create the toc entrys
• [-] validate docfx build
• [ ] test build it locally to see if we even still need the Reference or the api docs can replace them

For the last noted point I would need feedback from which we want to build api docs or if we need to exclude specific paths if there are generated things maybe 🤔 I usually build my docs using the csproj but I think its also possible to use the dll but this did not always produce the output I targeted in my repo.

(Marked the points where I am currently on with - which will become x if complete)

[stagep]

For now, I have just renamed that one file, added all the unstaged files, commited and now have pushed it to my repo https://github.com/stagep/MapsterWiki so I can now look at the .md files on Github in Preview and compare them to what is in the Mapster wiki. I wanted to be able to confirm that we have the same files in the Wiki that are in my repo.

https://github.com/MapsterMapper/Mapster/wiki https://github.com/stagep/MapsterWiki/blob/master/Home.md

are the same

https://github.com/MapsterMapper/Mapster/wiki/Basic-usages https://github.com/stagep/MapsterWiki/blob/master/Basic-usages.md

are the same

The sidebar is https://github.com/stagep/MapsterWiki/blob/master/_Sidebar.md

So now that there is access to the files, we can move forward.

[DocSvartz]

@stagep Great! You can correct the link in the side bar to Mapping-Configuration-With-IMapFrom-Interface? This page is missing in the wiki 😆

[stagep]

Done. The page is there without the quotes in the name.

[DocSvartz]

Ok, but it looks like you fixed the main repository (Mapster.Wiki) too. 👍
I meant the link there doesn't work anymore either.

[stagep]

I didn't touch the main repository. The link in my repository is to the page in the Mapster (wiki) repo. The issue was the link had %22 in it for the quote and the page did not have the %22.

https://github.com/MapsterMapper/Mapster/wiki/Mapping-Configuration-With-%22IMapFrom%22-Interface never existed but https://github.com/MapsterMapper/Mapster/wiki/Mapping-Configuration-With-IMapFrom-Interface was always there.

[stagep]

if you want my repo to be self referencing then I can change the content of _Sidebar.md. I would replace MapsterMapper/Mapster/wiki/ with stagep/MapsterWiki/blob/master/ and then the sidebar links in my repo would point to the .md files in my repo, not Mapster (wiki).

[DocSvartz]

Open https://github.com/MapsterMapper/Mapster/wiki/Mapping-Configuration-With-IMapFrom-Interface and in history will indicate that you are the only editor of this page.

Very strange things are happening :)

[DocSvartz]

I fixed the link to the current. It seems like nothing else is broken :)

[stagep]

This is what I did:

I created a local repository using https://github.com/MapsterMapper/Mapster.wiki.git as the source. I did a git add . to make the unstaged files staged and this made all the source control items disappear except for the D I added the missing .md file This changed the D to an R as we now had a renaming I committed this locally I created the repo https://github.com/stagep/MapsterWiki and pushed my local repo up to that repo. You can see my rename commit here: https://github.com/stagep/MapsterWiki/commit/c4d3e8d4b1c4f8df9e6133d078b2c0f310aa28a7

As you can see, my repo is there with all the files that were pulled from the wiki repo. I did this so as to not touch the Mapster repo. Normally, I would have forked the repo in Github but there is no Fork option on the wiki repo. I think that the one commit that I made created the missing file. This is the file in my repo here: https://github.com/stagep/MapsterWiki/blob/master/Mapping-Configuration-With-IMapFrom-Interface.md

[DocSvartz]

I think we were getting an error because we were running cloning on Windows. :) On Linux, the original file name Mapping-Configuration-With-"IMapFrom"-Interface.md was valid, and that's why everything worked on GitHub. @stagep Your repository still shows that the file was renamed, but for the wiki, it seems to be considered a new file.

[DevTKSS]

@DocSvartz @stagep hey there Just side note if you don't know yet:

• As you are speaking about the _Sidebar.md file I just would like to tell you that for docfx TOC aka Top and Sidebar navigation this file is the only one that will be replaced either way so you don't need to spend too much work on that to be fixed.
• The corrupted files content I did already copy over via editor so replaced this either way, but I could add a new git remote to pull down your changes to apply them 8f you want 👍

[stagep]

@DevTKSS We have the .md files in one place and the next step is to use these wiki content .md files and the README.md for the initial population of DocFx, if I understand things correctly. I am not making any further changes to my wiki repo.

I did have one question about the content at https://github.com/MapsterMapper/Mapster/releases . This is a GitHub generated page of CHANGELOG.md files. Will the change log pages continue to be content generated outside DocFx and DocFx will just have links in it's TOC to it such as:

Releases

Version 7

• 7.4.0
• 7.3.0 .and so on...

Version 6

• 6.5.1 .and so on...

Or do you also bring the releases docs under DocFx? AFAIK, there is no way to change the information shown under Releases except to have each releases page have a link to the DocFx generated releases page, which might appear a little hacky, your thoughts?

Regarding my example TOC, I do realize that Mapster.Tool is on it's own version schedule so I am using the Mapster version number only.

[DevTKSS]

@stagep depends on your answer to this:

1. How is the Changelog file generated ?
2. Where is it's output folder? Does it have one? - If yes, then I would simply suggest to add another event trigger in the docs deployment action that will get added along this PR and tell docfx to include this and where do we want it/them to be shown 👍

And I would need information to the image / icon we want to use if some:

We do have this link for the image in the README.md:

https://github.com/MapsterMapper/Mapster/blob/bab634544ff7838c1770ad4db2f6d68c4f733a19/README.md?plain=1#L1

but I was unable to find this anywhere. Can you tell me where I can find it or should I just download it from this url given? I think I heared of this image used for docfx needs to be relative to it, no web url 🤔

I am not making any further changes to my wiki repo.

that's the plan 👍 using docfx we will have the wiki in this repo at ./docs/* and you can simply edit them right there and then the gh action will be triggered:

name: Build and Deploy DocFX

on:
  push:
    branches: [ master ]
    paths:
      - 'docs/**'
      - 'README.md'
      - '.github/workflows/build-deploy-docs.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build-docs:
    if: ${{ github.ref == 'refs/heads/master' }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: |
            8.x
            9.x
      - name: Show dotnet version
        run: |
          dotnet --list-sdks
          dotnet --list-runtimes

      - name: Restore dependencies before docs deployment as recommended by docfx
        run: dotnet restore ./src/Mapster.sln

      - name: Build with dotnet
        run: dotnet build ./src/Mapster.sln

      - name: Run tests on .NET 9.0
        run: dotnet test --verbosity normal ./src/Mapster.sln

      - name: Install DocFX as .NET tool
        run: |
          dotnet tool update -g docfx
          docfx --version

      - name: Build docfx site
        working-directory: docs
        run: docfx docfx.json

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs/_site'

  deploy-docs:
    needs: build-docs
    if: ${{ needs.build-docs.result == 'success' && github.ref == 'refs/heads/master' }}
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Where I would like to have some second opinion who might be more expirienced with gh actions is, to eventually make the current build & test action (test is not actually needed for docs) maybe an action that can be reused from both, so we dont have duplicated code 🤔

Not sure also, if we really need to set environment because I initially generated this file for my repo and had some AI help, where it was creating a github-pages branch for this, which has been obsolete in the end. 🤔 the environment is still used from my master branch...

[DevTKSS]

@DocSvartz @stagep small state update 😃 I am on fixing the docfx build (link generation things) but if you like to see the current state, I pushed it up to my Mapster fork on this branch:

• https://github.com/DevTKSS/Mapster/tree/docs/add-docfx-docs-setup