gitlabmarkdowngitlab-wiki

Creeating a structured wiki page in GitLab


I'm trying to create a structured wiki page on GitLab using GitLab web interface. Here is the structure that I use for my home page:

# Introduction to the project

<details>
<summary>[Section1](Section1.md)</summary>

- [Subsection1](Section1.md#first)
- [Subsection2](Section1.md#second)
</details>

<details>
<summary>[Section2](Section2.md)</summary>

- [Subsection3](Subsection3.md):
  - [Subsubsection1](Subsection3.md#first)
  - [Subsubsection2](Subsection3.md#second)
  
- [Subsection4](Subsection4.md):
  - [Subsubsection1](Subsection4.md#first)
  - [Subsubsection2](Subsection4.md#second)
  - [Subsubsection3](Subsection4.md#third)

</details>

<details>
<summary>[Section3](Section3.md)</summary>

- [Subsection5](Subsection5.md):
  - [Subsubsection1](Subsection5.md#first)
  - [Subsubsection2](Subsection5.md#second)
  
- [Subsection6](Subsection6.md):
  - [Subsubsection1](Subsection6.md#first)
  - [Subsubsection2](Subsection6.md#second)
  
- [Subsection7](Subsection7.md):
  - [Subsubsection1](Subsection7.md#first)
  - [Subsubsection2](Subsection7.md#second)

</details>


# Conclusion
- Some conclusion
- Some conclusion


As you are probably aware for this I click on wiki button then I simply click on create a new page which allows me to create my first page which is by default home page. This gives me something like:

GitLab wiki home page

Then to create all those *.md files shown in my home page I simply click on the hyperlink of the relevant section in the home page which opens a new page asking me to create a new page where it by default fills the name of the file with an .md extension as you can see in the following image

creating a new page

So when I save the page it gives me the following

new markdown file

As you can see at the top of the page I can see the name of the markdown file with it's extension which is not desirable. So the first question is how should I get rid of the name of the markdown file and just keep the title mentioned in the markdown file using # Title.

And the second question is regarding the right hand side bar, I know that I can create a file called _sidebar.md by clicking on the gear icon on the upper right corner, but when I do this although i can customize the side bar the default pages stills remain there on the right hand side and don't disappear, is it normal?

By the way I'm trying to do all this on the GitLab web interface. Although if you suggest the solutions such as first doing all this on local and then push them to GitLab it would still be OK, just need it to work.


Solution

  • Here are some modifications to make in order to get rid of the undesired nuances such as the extension of the Markdown file in the header of the wiki pages.

    All Markdown-rendered headings automatically get IDs that can be linked to, except in comments.

    Although one way to work around this limitation would be using the HTML <a> tag with the id attribute.

    <a id="custom-label"></a>
    

    Place this <a> tag where you want to create a custom anchor. For example, after a heading or within a section of text.

    To link to this custom anchor from another part of the same Markdown file, you would use [Link Text](YourMarkdownFile#custom-label).

    This may or may not work, but you can try. There is a good chance that it wouldn't work since GitLab doesn't allow user-set HTML ID attributes in Markdown.

    In what concerns the side bar there are a couple of workarounds such as creating sidebar.yaml which is only supported in GitLab Premium and Ultimate editions.