How to comment on files


Me and my team are using GitLab to collaborate on a bunch of markdown documents we’re working on and we then use a python script to convert them to HTMLs and PDFs so our repository doesn’t contain any code, just a bunch of text files, most of them are markdown files.

All that is working just great. The only thing that we find challenging is the ability to write comments on the MD document we’re working on. Is there a way to add comments to the document in a similar way to the way MS-Word or Google Docs handles it? For example, to right click on a line in a file in the repo and add a comment and perhaps then convert them to issues that can be tracked?

The only ways I found so far to get anywhere near that goal were to either add a comment on the relevant line in the relevant commit of the file (which doesn’t allow to add comments on lines that were not modified as part of this commit) or to add issues with links to the relevant lines (which forces you to use two monitors - one with the relevant file open and the other with the issues panel which is quite cumbersome)

Are there any other ways to achieve that?



There isn’t currently a method of adding comments in that manner. What is the specific purpose of the comments that you are leaving on these lines? f you are attempting to reference multiple different lines within a document to collaborate with others, then creating an issue or working within a merge request would likely be the best route to do this in one space. If you can clearly identify what your use case is, then we can probably help determine if this is something that we should get within a feature request. :slight_smile:

Also, what are using to convert the documents to the HTML/PDF format? You can add HTML comments to markdown files when using pandoc, as it will ignore them completely. If your goal is to have a specific document clearly commented without anything being visible post conversion, this would likely be your best bet.


Thanks a lot for your reply.
In order to explain the purpose of the comments I’ll have to first tell you what are we currently doing with GitLab, It’s going to be a long post… so… I’m working as a consultant in a Cyber security consultancy company, as part of our normal day-to-day job, we have to compile MS-Word or PDF documents that contain the list of guidelines for our clients.
The way this currently works is that we try to find a client that is as similar as possible (in terms of the technology stack and business practices used) to the one we currently need to handle and then we simply copy the document we sent to that client and copy-paste bits and pieces from other clients to the new copy of the document and sometimes of course, also add new content to the document that is specific to that client. This document obviously contains lots of references both to public Internet content as well as other parts in the document. In addition to the MS-Word or PDF document we also compile a list of specific guidelines for this specific client by copying the entire document paragraph by paragraph to an MS-Excel column so that each paragraph is in a single line (for example the first paragraph is in A1 and the next one is in A2 and so on) and in the next 3 columns (B, C, D) we add initiatives that are specific to the client in order to help the client make the proposed guidelines (as they appear in the first column) a reality in a manageable fashion.

When I joined the company, about a year ago, I noticed that and since that I’ve worked a lot as a developer, I was very familiar with the way such things are done in the software development area, so I copied all the various paragraphs of the word document to several text files (in the MarkDown format). These files contain HTML bookmarks (more accurately - anchors) in various places in the files. These files will now serve as building blocks for the next projects, and developed Python code which uses WeasyPrint and a CSS file I wrote (and few images) to convert MarkDown content to PDF and created two new types of files: the first file type is what we call “framework” file which contains a list of building block file names that need to be included in the deliverable and the other file is what we call “initiatives” file which is essentially a YAML file that has initiatives linked to the various bookmarks (anchors) in the framework file. Then I upgraded the python code so that it can receive as a command line argument the name of the initiatives file, find its matching framework file, parse it to HTML (using the mistune package) and from HTML it converts it using my CSS to PDF (using the WeasyPrint package) and then parse the initiatives file (by using the pyyaml package) and generate another PDF that contains a table in which the framework file is copied as before to the first column and the matching initiatives are written to the columns to the right.

All this is store in an on-prem GitLab to allow us to have proper version control of all the building blocks and the deliverables that were sent to each client both as a PDF but also in a Markdown text form which is much easier to compare and manipulate.

Back when we worked on MS-Word, the project manager would just review the result document and add comments to the document and the rest of the team members would then create a copy of the file and fix the things that the project manager instructed them in the comments or reply to the comment if they had a different opinion then the project manager.

Now, I think that by switching to Markdown and YAML instead of MS-Word and MS-Excel I have simplified things, especially in terms of the ability to keep the template of the deliverables more homogenous across projects and since that now the code can also print some statistics of each project, and verify that each reference in the document is not broken or otherwise invalid.

The only thing I’m struggling with is the request from the project manager to be able to create comments on the deliverable in the way he was used to do that until now. I am very familiar with the abilities to create issues, manage them on kanban boards, comment on the lines that were changed during commits and the ability to create separate branches and let him review merge requests. They are all great ideas but they are still VERY different then the way he was USED TO handle this task before and that makes it extremely difficult for him to adjust to the new idea to the extent of rolling back to the old MS-Office way in the next project and completely abandoning the development that I did.

I know very well that this not the usual nor the standard GitLab usage, however, I think that by adding a relatively simple feature (because the comments on the file can be saved using the normal GitLab mechanisms such as issues that contain links to the relevant file@commit@line_number) it would make it possible and EASY for many other types of users and projects to store and manage their content in GitLab

Looking forward to hear from you,