Add metadata, title and intro text to the index file of the generated…

… docs (#272)

scripts/postProcessDocs.js

@@ -1,6 +1,22 @@
 const glob = require('glob')
 const { readFile, writeFile, unlink, renameSync } = require('fs')
 
+// The index file automatically generated by typedoc-plugin-markdown
+// only contains the list of modules of the package.
+// We'll add an introduction paragraph to that index file
+// and use metadata to place it in the first position.
+const indexIntroContents = `---
+sidebar_position: 1
+---
+
+# Arbitrum SDK
+
+[Arbitrum SDK](https://github.com/OffchainLabs/arbitrum-sdk) is a typescript library for client-side interactions with Arbitrum. It provides common helper functionality as well as access to the underlying smart contract interfaces.
+        
+Below is a list of modules of the library. See the [tutorials](https://github.com/OffchainLabs/arbitrum-tutorials) for further examples of how to use these classes.
+`
+
+// Traverse all typedoc generated md files
 glob('./docs/**/*', function (err, res) {
   if (err) {
     console.log('Error', err)
@@ -20,16 +36,39 @@ glob('./docs/**/*', function (err, res) {
       }
 
       // Set the new index file
-      // The 01- prefix tells docusaurus to set this page as the first one in the
-      // sidebar menu
-      // https://docusaurus.io/docs/sidebar/autogenerated#using-number-prefixes
       if (path.includes('modules.md')) {
-        renameSync(path, path.replace('modules', '01-index'), function (err) {
+        // Renaming the file to serve it as the index
+        const indexPath = path.replace('modules', 'index')
+        renameSync(path, indexPath, function (err) {
           if (err) {
             console.log(err)
             return
           }
         })
+
+        // Modifying the file contents
+        //  - Remove the automatically generated title
+        //  - Add metadata, a new title + an intro text
+        readFile(indexPath, 'utf-8', function (err, contents) {
+          if (err) {
+            console.log(err)
+            return
+          }
+
+          // Remove the automatically generated title
+          const [, ...linesWithoutFirstLine] = contents.split('\n')
+          const newFileContent = linesWithoutFirstLine.join('\n').trim()
+
+          // Write the updated contents to the file
+          writeFile(
+            indexPath,
+            `${indexIntroContents}\n${newFileContent}`,
+            'utf-8',
+            function (err) {
+              if (err) console.warn('Error', err)
+            }
+          )
+        })
         continue
       }
 
@@ -41,7 +80,6 @@ glob('./docs/**/*', function (err, res) {
         }
 
         // Fix JSX md rendering breaking tags (only <T> tags break docusaurus, so we keep the rest):
-        // const replaced = contents.replace(/</g, '&lt;').replace(/>/g, '&gt;')
         const replaced = contents.replace(/<T>/g, '&lt;T&gt;')
         writeFile(path, replaced, 'utf-8', function (err) {
           if (err) console.warn('Error', err)