[#2318] Rename title.md (#2516)

Rename title.md

This pull request updates the dashboard's introductory section to use
`intro.md` instead of the legacy  `title.md`, improving clarity
across documentation, frontend, and backend code. Legacy support for
`title.md` remains for backward compatibility, but
users are encouraged to migrate to `intro.md`. 

The changes also update documentation to reflect this new approach
and clarify the difference between the browser tab title and the
dashboard intro section.

Author: ashmitahaldar

build.gradle

@@ -342,6 +342,7 @@ def syncFrontendPublic = tasks.register('syncFrontendPublic', Sync) {
     preserve {
         include 'index.html'
         include 'favicon.ico'
+        include 'intro.md'
         include 'title.md'
         include 'logo.png'
     }

docs/ug/cli.md

@@ -31,7 +31,7 @@ The section below provides explanations for each of the flags.
 **`--analyze-authorship`**: Performs further analysis to distinguish between partial and full credit attribution for
 lines of code assigned to the author.
 
-* Default: this feature is turned ***off*** by default and the author will receive partial credits for all lines of
+* Default: this feature is turned **_off_** by default and the author will receive partial credits for all lines of
   code, as the code lines are at least partial credit but may not qualify for full credit.
 * Alias: `-A` (upper case)
 * Example: `--analyze-authorship` or `-A`
@@ -267,12 +267,12 @@ Cannot be used with `--last-modified-date`. This may result in an incorrect last
 
 ### `--text`, `-T`
 
-**`--text`**: Refreshes text content (title.md, repo-blurbs.md and author-blurbs.md) without reanalyzing repository data.
+**`--text`**: Refreshes text content (intro.md/title.md, repo-blurbs.md and author-blurbs.md) without reanalyzing repository data.
 * Alias: `-T` (uppercase T)
 
 <box type="info" seamless>
 
-* This flag is used to update only the text content (title.md, repo-blurbs.md and author-blurbs.md) of the report. The new report will be generated with the existing data from the previous report.
+* This flag is used to update only the text content (intro.md/title.md, repo-blurbs.md and author-blurbs.md) of the report. The new report will be generated with the existing data from the previous report.
 * Ensure that there is an existing valid report generated before using this flag.
 * Cannot be used with any other flags except from `--view`, `--assets` and `--config`.
 </box>

docs/ug/customizingReports.md

@@ -90,12 +90,24 @@ There is a default `favicon.ico` file provided in the template zip folder. If yo
 
 ##### Add a title
 
-A title component can be added by creating a file titled `title.md` in the config directory.
+### Personalizing Reports
 
-The title can render a combination of Markdown/HTML and plaintext ([example](https://github.com/reposense/RepoSense/blob/master/docs/ug/title.md)), and will appear on the top of the left panel as shown below:
-![Title Component Example](../images/title-example.png)
+#### Add favicon.ico
+There is a default `favicon.ico` file provided in the template zip folder. If you want to self-configure the `favicon.ico`, please ensure that the file is valid and has the file name of `favicon.ico`. This icon will appear in the browser tab when your report is viewed. Copy or move your `favicon.ico file` into the `assets` folder of the config directory 
 
-Do note that the width of the title is bound by the width of the left panel.
+Specifying the config directory can be done as follows:
+{{ embed("Appendix: **CLI syntax reference → `config` flag**", "cli.md#section-config") }}
+
+#### Add an intro
+Add the introductory section of the dashboard by creating an `intro.md` file in the config directory. Existing `title.md` files still work for now, but will be deprecated in favour of `intro.md`.
+
+Specifying the config directory can be done as follows:
+{{ embed("Appendix: **CLI syntax reference → `config` flag**", "cli.md#section-config") }}
+
+The intro can render a combination of Markdown/HTML and plaintext ([example](https://github.com/reposense/RepoSense/blob/master/docs/ug/title.md)), and will appear on the top of the left panel as shown below:
+![Intro Component Example](../images/title-example.png)
+
+Do note that the width of the intro is bound by the width of the left panel.
 
 For more information on how to use Markdown, see the [Markdown Guide](https://www.markdownguide.org/).
 

docs/ug/reportConfig.md

@@ -45,6 +45,12 @@ repos:
 
 <box type="info" seamless>
 
+The `title` field controls the browser tab text (the HTML `<title>` element). To customize the description that appears at the top of the dashboard itself, provide an `intro.md` file as described [here](./customizingReports.html#add-an-intro).
+
+</box>
+
+<box type="info" seamless>
+
 The `author-display-name`, `author-git-author-name` and `author-emails` fields are optional.
 
 However, users are encouraged to add their Git author name `author-git-author-name` and emails `author-emails` in their Git configuration related to their commits so that

frontend/cypress/support.js

@@ -9,6 +9,6 @@ beforeEach(() => {
   cy.visit('/');
   cy.intercept({
     method: 'GET',
-    url: '/title.md',
-  }, '# RepoSense Intro').as('getTitleMd');
+    url: '/intro.md',
+  }, '# RepoSense Intro').as('getIntroMd');
 });

frontend/src/components/c-intro.vue

@@ -0,0 +1,59 @@
+<template lang="pug">
+.intro
+  c-markdown-chunk(:markdown-text="markdownText")
+</template>
+
+<script lang="ts">
+import { defineComponent } from "vue";
+import CMarkdownChunk from "./c-markdown-chunk.vue";
+
+const INTRO_FILE_PATH = "intro.md";
+const LEGACY_TITLE_FILE_PATH = "title.md";
+
+export default defineComponent({
+  name: "c-intro",
+  components: { CMarkdownChunk },
+  data() {
+    return {
+      markdownText: "",
+    };
+  },
+  async beforeMount() {
+    try {
+      const introText = await this.fetchMarkdown(INTRO_FILE_PATH);
+      if (introText) {
+        this.markdownText = introText;
+        return;
+      }
+
+      const legacyText = await this.fetchMarkdown(LEGACY_TITLE_FILE_PATH);
+      if (legacyText) {
+        console.warn(
+          "Detected deprecated title.md. Please rename it to intro.md.",
+        );
+      }
+      this.markdownText = legacyText;
+    } catch (error) {
+      this.markdownText = (error as Error).toString();
+    }
+  },
+  methods: {
+    async fetchMarkdown(path: string): Promise<string> {
+      const response = await fetch(path);
+      if (!response.ok) {
+        return "";
+      }
+      return response.text();
+    },
+  },
+});
+</script>
+
+<style lang="scss" scoped>
+.intro {
+  overflow-x: auto;
+  padding: 0 1.5rem;
+  // This is needed because the parent summary-wrapper center aligns everything
+  text-align: initial;
+}
+</style>

frontend/src/components/c-title.vue

@@ -4,7 +4,7 @@
     c-resizer
       template(#left)
         #summary-wrapper
-          c-title(ref="cTitle")
+          c-intro(ref="cIntro")
           c-summary.tab-padding(
             v-if="!isPortfolio",
             ref="summary",
@@ -78,7 +78,7 @@
 <script lang='ts'>
 import { defineComponent } from 'vue';
 
-import cTitle from '../components/c-title.vue';
+import cIntro from '../components/c-intro.vue';
 import cResizer from '../components/c-resizer.vue';
 import cZoom from './c-zoom.vue';
 import cSummary from './c-summary.vue';
@@ -88,7 +88,7 @@ import cAuthorship from './c-authorship.vue';
 const home = defineComponent({
   name: 'c-home',
   components: {
-    cTitle,
+    cIntro,
     cResizer,
     cZoom,
     cSummary,

frontend/src/views/c-home.vue

@@ -24,7 +24,7 @@ export default defineConfig(({ mode }) => {
     plugins: [vue(), eslint(), stylelint()],
     // This is to disable default fallback behaviour of
     // displaying the head tag of the html in case of
-    // missing 'title.md' file
+    // missing 'intro.md' file
     appType: 'mpa',
     resolve: {
       extensions: ['.ts', '.vue'],

frontend/vite.config.mts

@@ -97,7 +97,7 @@ public class ReportGenerator {
     private static final String LOG_ERROR_CLONING_OR_BRANCHING = "Exception met while cloning or checking out.";
     private static final String LOG_UNEXPECTED_ERROR = "Unexpected error stack trace for %s:\n>%s";
     private static final List<String> assetsFilesWhiteList =
-            Collections.unmodifiableList(Arrays.asList(new String[] {"assets/favicon.ico", "title.md"}));
+             Collections.unmodifiableList(Arrays.asList(new String[] { "assets/favicon.ico", "intro.md" }));
 
     private LocalDateTime earliestSinceDate = null;
 
@@ -198,7 +198,6 @@ public List<Path> generateReposReport(List<RepoConfiguration> configs, String ou
         this.globalSinceDate = TimeUtil.isEqualToArbitraryFirstDateConverted(this.globalSinceDate, zoneId)
                 ? earliestSinceDate : this.globalSinceDate;
 
-
         Optional<Path> summaryPath = FileUtil.writeJsonFile(
                 new SummaryJson(configs, reportConfig, generationDate,
                         this.globalSinceDate, this.globalUntilDate, isSinceDateProvided,