How to host HTML documentation in a Gitlab project?

Hi. I’m new to Gitlab.

My project has a couple of pages of Markdown documentation, that are rendered to HTML for viewing. I want them to be readable in my project’s Gitlab pages. You shouldn’t need to download everything just to read the documentation. And the pages should be readable standalone (after being downloaded) as well.

I know that pages written in markdown are rendered for viewing by Gitlab. But my pages need HTML versions, so they can be read after they have been downloaded. The links inside of the pages need to be links to the HTML versions.

I could link to the markdown versions, but then the links are broken after downloading. And I use some markdown features (of pandoc) that aren’t available in Gitlab.

How should I set that up? Can HTML pages be stored for viewing in a Gitlab project?

Cheers, Volker

1 Like

@volkerwysk Unfortunately, the person above just faked post with links to spam URL’s which were exactly the same page each time with nothing related to Gitlab or the topic or content that he was posting.

Better would be to check out the Gitlab pages link here: GitLab Pages | GitLab which is official Gitlab documentation.

I’ve reported their post as spam, despite the fact they have tried to make it look legitimate they haven’t provided you with anything useful to help solve your problem.

You can use most static-site-generators, SSG’s for hosting pages on Gitlab Pages so you don’t even need to do what that person recommended, which wasn’t great at best. The SSG’s will have the directory/file structure exactly like you want and need it to be.

The official documentation link I provided even gives you documented examples/tutorials.

Hi. Thanks for warning me.

| iwalker
August 2 |

  • | - |

@volkerwysk Unfortunately, the person above just faked post with links to spam URL’s which were exactly the same page each time with nothing related to Gitlab or the topic or content that he was posting.

Better would be to check out the Gitlab pages link here: GitLab Pages | GitLab which is official Gitlab documentation.

That’s much too complicated, if you just want to make a few static HTML pages browsable. I’ve given up for now.

I’ve reported their post as spam, despite the fact they have tried to make it look legitimate they haven’t provided you with anything useful to help solve your problem.

You can use most static-site-generators, SSG’s for hosting pages on Gitlab Pages so you don’t even need to do what that person recommended, which wasn’t great at best. The SSG’s will have the directory/file structure exactly like you want and need it to be.

The official documentation link I provided even gives you documented examples/tutorials.

Regards,
Volker

If it’s too complicated using an SSG like astro.build with Gitlab pages, then you probably should be looking at shared hosting, or a VPS where you just set up Apache on a Linux server, and then download the content you require and use pandoc or whatever you have been using to generate the html pages and host it that way.

It would be easy enough to do that by cloning the repository or downloading the files you need and build it that way.

Alternatively, just use the wiki functionality in Gitlab under your repository since these will be rendered markdown browseable in your web browser like the rest of your repository.

I guess it all depends on what method is easier for you, or whether you are willing to put more effort in to use the SSG. Once you have that all set up, it’s pretty easy after that. But that’s something you need to decide about if you have the time for it or not. I’m pretty sure statically generated html files can be deployed in Gitlab pages as well without an SSG, but you still need to read the Gitlab Pages documentation and follow the examples/tutorials to find out how to do it.

| iwalker
August 2 |

  • | - |

If it’s too complicated using an SSG like astro.build with Gitlab pages, then you probably should be looking at shared hosting, or a VPS where you just set up Apache on a Linux server, and then download the content you require and use pandoc or whatever you have been using to generate the html pages and host it that way.

I’m already running my personal website on a shared web server. But I haven’t used a Static Website Generator, yet.

It would be easy enough to do that by cloning the repository or downloading the files you need and build it that way.

Alternatively, just use the wiki functionality in Gitlab under your repository since these will be rendered markdown browseable in your web browser like the rest of your repository.

Yes, I’m doing this, as a substitute for having browsable HTML pages in one of my projects. But you can upload/change pages only through the web interface. - Or not?

I guess it all depends on what method is easier for you, or whether you are willing to put more effort in to use the SSG. Once you have that all set up, it’s pretty easy after that. But that’s something you need to decide about if you have the time for it or not. I’m pretty sure statically generated html files can be deployed in Gitlab pages as well without an SSG, but you still need to read the Gitlab Pages documentation and follow the examples/tutorials to find out how to do it.

I found the Gitlab documentation a little hard (effortful) to follow. I don’t want to have to deal with Docker images, YML-files, SSGs and more, when I just have a couple of static HTML pages…

Cheers,
Volker

I use https://astro.build but I host it myself on my own VPS - the only difference being there is a learning curve for developing the pages at first. At the beginning it was far easier for me to just continue with HTML5, CSS, JS, but I’m slowly getting into it with Astro, and I like some of the features it offers. But that’s just me :slight_smile:

If you are doing it with Gitlab Page, then you can automate it. When you change something, the CI/CD should then start and build the new site with the changes you made. I don’t use it personally, but I know it’s possible.

Totally understand that, especially if you just want it to work with minimal effort. Although once you’ve got it running, it will be far easier for it all to maintain itself in the future. You make code changes, CI/CD takes over, new website deployed. But the beginning would be a little time-consuming at first to get it all sorted.

| iwalker
August 2 |

  • | - |

volkerwysk:

I’m already running my personal website on a shared web server. But I haven’t used a Static Website Generator, yet.

I use https://astro.build but I host it myself on my own VPS - the only difference being there is a learning curve for developing the pages at first. At the beginning it was far easier for me to just continue with HTML5, CSS, JS, but I’m slowly getting into it with Astro, and I like some of the features it offers. But that’s just me :slight_smile:

That Astro website is well-polished… But that’s what is to expect from a SSG. :wink:

volkerwysk:

Yes, I’m doing this, as a substitute for having browsable HTML pages in one of my projects. But you can upload/change pages only through the web interface. - Or not?

If you are doing it with Gitlab Page, then you can automate it. When you change something, the CI/CD should then start and build the new site with the changes you made. I don’t use it personally, but I know it’s possible.

volkerwysk:

I found the Gitlab documentation a little hard (effortful) to follow. I don’t want to have to deal with Docker images, YML-files, SSGs and more, when I just have a couple of static HTML pages…

Totally understand that, especially if you just want it to work with minimal effort. Although once you’ve got it running, it will be far easier for it all to maintain itself in the future. You make code changes, CI/CD takes over, new website deployed. But the beginning would be a little time-consuming at first to get it all sorted.

Yeah, I want it to “just work”, if that’s possible. Therefore I have placed the documentation of the mentioned one of my (two at the time being) Gitlab projects on my website. I might dig into SSGs, however.

Cheers,
Volker