Merge branch 'main' into release

Author: hatton

README.md

@@ -17,13 +17,13 @@ You can name it anything you like, e.g. "Documentation Root".
 
 ## 3. Create a Notion Integration
 
-In order for docu-notion to read your site via Notion's API, you need to create what Notion calls an "integration". Follow [these instructions](https://developers.notion.com/docs/getting-started) to make an integration and get your token. Limit your integration to "READ" access.
+In order for docu-notion to read your site via Notion's API, you need to create what Notion calls an "integration". Follow [these instructions](https://developers.notion.com/docs/getting-started) to make an integration and get your token. Remember to limit your integration to "READ" access.
 
-## 4. "Invite" your Notion Integration to read you page
+## 4. Connect your Integration
 
-In Notion, click "Share" on the root of your documentation and "invite" your integration to it.
+Go to the page that will be the root of your site. This page should have, as direct children, your "Outline" (required) and "Database" (optional) pages. Follow [these instructions](https://developers.notion.com/docs/create-a-notion-integration#give-your-integration-page-permissions).
 
-![image](https://user-images.githubusercontent.com/8448/168930238-1dcf46df-a690-4839-bf4c-c63157f104d8.png)
+<img width="318" alt="image" src="https://github.com/sillsdev/docu-notion/assets/8448/810c6dca-f9ab-4370-93b4-dc1479332af7">
 
 ## 5. Add your pages under your Outline page.
 
@@ -35,7 +35,7 @@ First, determine the id of your root page by clicking "Share" and looking at the
 https://www.notion.so/hattonjohn/My-Docs-0456aa5842946bdbea3a4f37c97a0e5
 means that the id is "0456aa5842946PRETEND4f37c97a0e5".
 
-Determine where you want the markdown files and images to land. The following works well for Docusaurus instances:
+Try it out:
 
 ```
 npx @sillsdev/docu-notion -n secret_PRETEND123456789PRETEND123456789PRETEND6789 -r 0456aa5842946PRETEND4f37c97a0e5"

src/latex.spec.ts

@@ -0,0 +1,106 @@
+import { NotionToMarkdown } from "notion-to-md";
+import { HierarchicalNamedLayoutStrategy } from "./HierarchicalNamedLayoutStrategy";
+import { LayoutStrategy } from "./LayoutStrategy";
+import { NotionPage } from "./NotionPage";
+
+import { getMarkdownFromNotionBlocks } from "./transform";
+
+import { IDocuNotionContext } from "./plugins/pluginTypes";
+import { convertInternalUrl } from "./plugins/internalLinks";
+
+import { initNotionClient } from "./pull";
+import { NotionBlock } from "./types";
+
+import { IDocuNotionConfig } from "./config/configuration";
+
+import defaultConfig from "./config/default.docunotion.config";
+
+test("Latex Rendering", async () => {
+  const pages = new Array<NotionPage>();
+  const counts = {
+    output_normally: 0,
+    skipped_because_empty: 0,
+    skipped_because_status: 0,
+    skipped_because_level_cannot_have_content: 0,
+  };
+
+  const notionClient = initNotionClient("");
+
+  const layoutStrategy = new HierarchicalNamedLayoutStrategy();
+
+  const config: IDocuNotionConfig = defaultConfig;
+
+  const context: IDocuNotionContext = {
+    getBlockChildren: (id: string) => {
+      return new Promise<NotionBlock[]>(resolve =>
+        resolve(new Array<NotionBlock>())
+      );
+    },
+    directoryContainingMarkdown: "", // this changes with each page
+    relativeFilePathToFolderContainingPage: "", // this changes with each page
+    layoutStrategy: layoutStrategy,
+    notionToMarkdown: new NotionToMarkdown({ notionClient }),
+    options: {
+      notionToken: "",
+      rootPage: "",
+      locales: [""],
+      markdownOutputPath: "",
+      imgOutputPath: "",
+      imgPrefixInMarkdown: "",
+      statusTag: "",
+    },
+
+    pages: pages,
+    counts: counts, // review will this get copied or pointed to?
+    imports: [],
+    convertNotionLinkToLocalDocusaurusLink: (url: string) =>
+      convertInternalUrl(context, url),
+  };
+
+  const blocks: Array<NotionBlock> = [
+    {
+      object: "block",
+      id: "169e1c47-6706-4518-adca-73086b2738ac",
+      parent: {
+        type: "page_id",
+        page_id: "2acc11a4-82a9-4759-b429-fa011c164888",
+      },
+      created_time: "2023-08-18T15:51:00.000Z",
+      last_edited_time: "2023-08-18T15:51:00.000Z",
+      created_by: {
+        object: "user",
+        id: "af5c163e-82b1-49d1-9f1c-539907bb9fb9",
+      },
+      last_edited_by: {
+        object: "user",
+        id: "af5c163e-82b1-49d1-9f1c-539907bb9fb9",
+      },
+      has_children: false,
+      archived: false,
+      type: "paragraph",
+      paragraph: {
+        rich_text: [
+          {
+            type: "equation",
+            equation: { expression: "x" },
+            annotations: {
+              bold: false,
+              italic: false,
+              strikethrough: false,
+              underline: false,
+              code: false,
+              color: "default",
+            },
+            plain_text: "x",
+            href: null,
+          },
+        ],
+        color: "default",
+      },
+    },
+  ];
+
+  expect(await getMarkdownFromNotionBlocks(context, config, blocks)).toContain(
+    "$x$"
+  );
+});

src/pull.ts

@@ -57,7 +57,7 @@ export async function notionPull(options: DocuNotionOptions): Promise<void> {
   const optionsForLogging = { ...options };
   // Just show the first few letters of the notion token, which start with "secret" anyhow.
   optionsForLogging.notionToken =
-    optionsForLogging.notionToken.substring(0, 3) + "...";
+    optionsForLogging.notionToken.substring(0, 10) + "...";
 
   const config = await loadConfigAsync();
 
@@ -80,6 +80,24 @@ export async function notionPull(options: DocuNotionOptions): Promise<void> {
 
   info("Connecting to Notion...");
 
+  // Do a  quick test to see if we can connect to the root so that we can give a better error than just a generic "could not find page" one.
+  try {
+    await executeWithRateLimitAndRetries("retrieving root page", async () => {
+      await notionClient.pages.retrieve({ page_id: options.rootPage });
+    });
+  } catch (e: any) {
+    error(
+      `docu-notion could not retrieve the root page from Notion. \r\na) Check that the root page id really is "${
+        options.rootPage
+      }".\r\nb) Check that your Notion API token (the "Integration Secret") is correct. It starts with "${
+        optionsForLogging.notionToken
+      }".\r\nc) Check that your root page includes your "integration" in its "connections".\r\nThis internal error message may help:\r\n    ${
+        e.message as string
+      }`
+    );
+    exit(1);
+  }
+
   group(
     "Stage 1: walk children of the page named 'Outline', looking for pages..."
   );