✏️ Rename Toc -> TOC (#1177)

* refactor: rename Toc -> TOC

* chore: add changeset

.changeset/wet-beds-change.md

@@ -0,0 +1,7 @@
+---
+"myst-common": minor
+"myst-cli": minor
+"mystmd": patch
+---
+
+Rename Toc to TOC

packages/myst-cli/src/build/init.ts

@@ -41,7 +41,7 @@ const SITE_CONFIG = `site:
 export type InitOptions = {
   project?: boolean;
   site?: boolean;
-  writeToc?: boolean;
+  writeTOC?: boolean;
   ghPages?: boolean;
   ghCurvenote?: boolean;
 };
@@ -61,12 +61,12 @@ Learn more about this CLI and MyST Markdown at: ${chalk.bold('https://mystmd.org
 `;
 
 export async function init(session: ISession, opts: InitOptions) {
-  const { project, site, writeToc, ghPages, ghCurvenote } = opts;
+  const { project, site, writeTOC, ghPages, ghCurvenote } = opts;
 
   if (ghPages) return githubPagesAction(session);
   if (ghCurvenote) return githubCurvenoteAction(session);
 
-  if (!project && !site && !writeToc) {
+  if (!project && !site && !writeTOC) {
     session.log.info(WELCOME());
   }
   loadConfig(session, '.');
@@ -118,12 +118,12 @@ export async function init(session: ISession, opts: InitOptions) {
     );
     fs.writeFileSync(configFile, configData);
   }
-  if (writeToc) {
+  if (writeTOC) {
     loadConfig(session, '.');
-    await loadProjectFromDisk(session, '.', { writeToc });
+    await loadProjectFromDisk(session, '.', { writeTOC });
   }
   // If we have any options, this command is complete!
-  if (writeToc || project || site) return;
+  if (writeTOC || project || site) return;
   session.log.info(''); // New line
   const promptStart = await inquirer.prompt([
     {

packages/myst-cli/src/build/meca/index.ts

@@ -11,7 +11,7 @@ import { VFile } from 'vfile';
 import { createManifestXml, type ManifestItem } from 'meca';
 import { runJatsExport } from '../jats/single.js';
 import { loadFile } from '../../process/file.js';
-import { writeTocFromProject } from '../../project/toToc.js';
+import { writeTOCFromProject } from '../../project/toTOC.js';
 import type { LocalProjectPage } from '../../project/types.js';
 import type { ISession } from '../../session/types.js';
 import { castSession } from '../../session/cache.js';
@@ -294,7 +294,7 @@ export async function runMecaExport(
     if (fs.existsSync(path.join(projectPath, '_toc.yml'))) {
       copyFileToFolder(session, path.join(projectPath, '_toc.yml'), bundle, fileCopyErrorLogFn);
     } else {
-      writeTocFromProject(project, bundle);
+      writeTOCFromProject(project, bundle);
     }
     addManifestItem(manifestItems, 'article-source', mecaFolder, path.join(bundle, '_toc.yml'));
     // Write all source markdown/ipynb/etc files

packages/myst-cli/src/build/utils/collectExportOptions.ts

@@ -12,7 +12,7 @@ import { VFile } from 'vfile';
 import { findCurrentProjectAndLoad } from '../../config.js';
 import { logMessagesFromVFile } from '../../utils/logging.js';
 import { validateTOC } from '../../utils/toc.js';
-import { projectFromToc } from '../../project/fromToc.js';
+import { projectFromTOC } from '../../project/fromTOC.js';
 import { loadProjectFromDisk } from '../../project/load.js';
 import type { LocalProject } from '../../project/types.js';
 import type { ISession } from '../../session/types.js';
@@ -74,7 +74,7 @@ function resolveArticlesFromTOC(
     ExportFormats.pdf,
     ExportFormats.pdftex,
   ].includes(exp.format);
-  const proj = projectFromToc(session, tocPath, allowLevelLessThanOne ? -1 : 1);
+  const proj = projectFromTOC(session, tocPath, allowLevelLessThanOne ? -1 : 1);
   return resolveArticlesFromProject(exp, proj, vfile);
 }
 
@@ -159,9 +159,9 @@ export function resolveArticles(
   let resolved: ResolvedArticles = { articles, sub_articles };
   // First, respect explicit toc. If articles/sub_articles are already defined, toc is ignored.
   if (exp.toc && !resolved.articles && !resolved.sub_articles) {
-    const resolvedToc = path.resolve(path.dirname(sourceFile), exp.toc);
-    if (validateTOC(session, resolvedToc)) {
-      resolved = resolveArticlesFromTOC(session, exp, resolvedToc, vfile);
+    const resolvedTOC = path.resolve(path.dirname(sourceFile), exp.toc);
+    if (validateTOC(session, resolvedTOC)) {
+      resolved = resolveArticlesFromTOC(session, exp, resolvedTOC, vfile);
     }
   }
   // If no articles are specified, use the sourceFile for article

packages/myst-cli/src/process/site.ts

@@ -52,7 +52,7 @@ export type ProcessFileOptions = {
 
 export type ProcessProjectOptions = ProcessFileOptions & {
   watchMode?: boolean;
-  writeToc?: boolean;
+  writeTOC?: boolean;
   writeFiles?: boolean;
   reloadProject?: boolean;
   checkLinks?: boolean;
@@ -136,7 +136,7 @@ export async function addProjectReferencesToObjectsInv(
 export async function loadProject(
   session: ISession,
   projectPath: string,
-  opts?: { writeToc?: boolean; reloadProject?: boolean },
+  opts?: { writeTOC?: boolean; reloadProject?: boolean },
 ) {
   const project = await loadProjectFromDisk(session, projectPath, {
     warnOnNoConfig: true,
@@ -286,7 +286,7 @@ export async function processProject(
     extraLinkTransformers,
     extraTransforms,
     watchMode,
-    writeToc,
+    writeTOC,
     writeFiles = true,
     reloadProject,
     execute,
@@ -301,7 +301,7 @@ export async function processProject(
     throw Error('Unable to process project');
   }
   const { project, pages } = await loadProject(session, siteProject.path, {
-    writeToc: writeFiles && writeToc,
+    writeTOC: writeFiles && writeTOC,
     reloadProject,
   });
   if (!watchMode) {

packages/myst-cli/src/project/fromPath.ts

@@ -10,7 +10,7 @@ import { fileInfo } from '../utils/fileInfo.js';
 import { nextLevel } from '../utils/nextLevel.js';
 import { VALID_FILE_EXTENSIONS, isValidFile } from '../utils/resolveExtension.js';
 import { shouldIgnoreFile } from '../utils/shouldIgnoreFile.js';
-import { pagesFromToc } from './fromToc.js';
+import { pagesFromTOC } from './fromTOC.js';
 import type {
   PageLevels,
   LocalProjectFolder,
@@ -60,15 +60,15 @@ function projectPagesFromPath(
   if (contents.includes(join(path, '_toc.yml'))) {
     const prevLevel = (level < 2 ? 1 : level - 1) as PageLevels;
     try {
-      return pagesFromToc(session, path, prevLevel);
+      return pagesFromTOC(session, path, prevLevel);
     } catch {
       if (!suppressWarnings) {
         addWarningForFile(
           session,
           join(path, '_toc.yml'),
           `Invalid table of contents ignored`,
           'warn',
-          { ruleId: RuleId.validToc },
+          { ruleId: RuleId.validTOC },
         );
       }
     }

packages/myst-cli/src/project/fromToc.ts → packages/myst-cli/src/project/fromTOC.ts

@@ -61,7 +61,7 @@ function pagesFromChapters(
  * and the first "chapter" level will be 0; However, "sections"
  * will never be level < 1.
  */
-export function projectFromToc(
+export function projectFromTOC(
   session: ISession,
   path: string,
   level: PageLevels = 1,
@@ -113,12 +113,12 @@ export function projectFromToc(
  *
  * The root file is converted into just another top-level page.
  */
-export function pagesFromToc(
+export function pagesFromTOC(
   session: ISession,
   path: string,
   level: PageLevels,
 ): (LocalProjectFolder | LocalProjectPage)[] {
-  const { file, index, pages } = projectFromToc(session, path, nextLevel(level));
+  const { file, index, pages } = projectFromTOC(session, path, nextLevel(level));
   pages.unshift({ file, slug: index, level });
   return pages;
 }

packages/myst-cli/src/project/index.ts

@@ -1,5 +1,5 @@
 export * from './fromPath.js';
-export * from './fromToc.js';
+export * from './fromTOC.js';
 export * from './load.js';
-export * from './toToc.js';
+export * from './toTOC.js';
 export * from './types.js';

packages/myst-cli/src/project/load.ts

@@ -12,8 +12,8 @@ import { addWarningForFile } from '../utils/addWarningForFile.js';
 import { getAllBibTexFilesOnPath } from '../utils/getAllBibtexFiles.js';
 import { validateTOC } from '../utils/toc.js';
 import { projectFromPath } from './fromPath.js';
-import { projectFromToc } from './fromToc.js';
-import { writeTocFromProject } from './toToc.js';
+import { projectFromTOC } from './fromTOC.js';
+import { writeTOCFromProject } from './toTOC.js';
 import type { LocalProject, LocalProjectPage } from './types.js';
 
 /**
@@ -31,7 +31,7 @@ import type { LocalProject, LocalProjectPage } from './types.js';
 export async function loadProjectFromDisk(
   session: ISession,
   path?: string,
-  opts?: { index?: string; writeToc?: boolean; warnOnNoConfig?: boolean; reloadProject?: boolean },
+  opts?: { index?: string; writeTOC?: boolean; warnOnNoConfig?: boolean; reloadProject?: boolean },
 ): Promise<LocalProject> {
   path = path || resolve('.');
   if (!opts?.reloadProject) {
@@ -50,12 +50,12 @@ export async function loadProjectFromDisk(
     );
   }
   let newProject: Omit<LocalProject, 'bibliography'> | undefined;
-  let { index, writeToc } = opts || {};
+  let { index, writeTOC } = opts || {};
   const projectConfigFile = selectors.selectLocalConfigFile(session.store.getState(), path);
   if (validateTOC(session, path)) {
-    newProject = projectFromToc(session, path);
-    if (writeToc) session.log.warn('Not writing the table of contents, it already exists!');
-    writeToc = false;
+    newProject = projectFromTOC(session, path);
+    if (writeTOC) session.log.warn('Not writing the table of contents, it already exists!');
+    writeTOC = false;
   } else {
     const project = selectors.selectLocalProject(session.store.getState(), path);
     if (!index && !project?.implicitIndex && project?.file) {
@@ -67,14 +67,14 @@ export async function loadProjectFromDisk(
   if (!newProject) {
     throw new Error(`Could not load project from ${path}`);
   }
-  if (writeToc) {
+  if (writeTOC) {
     try {
       session.log.info(
         `📓 Writing '_toc.yml' file to ${path === '.' ? 'the current directory' : path}`,
       );
-      writeTocFromProject(newProject, path);
+      writeTOCFromProject(newProject, path);
       // Re-load from TOC just in case there are subtle differences with resulting project
-      newProject = projectFromToc(session, path);
+      newProject = projectFromTOC(session, path);
     } catch {
       addWarningForFile(
         session,

packages/myst-cli/src/project/toToc.ts → packages/myst-cli/src/project/toTOC.ts

@@ -80,7 +80,7 @@ export function tocFromProject(project: PartialLocalProject, path = '.') {
   return toc;
 }
 
-export function writeTocFromProject(project: PartialLocalProject, path: string) {
+export function writeTOCFromProject(project: PartialLocalProject, path: string) {
   const filename = join(path, '_toc.yml');
   const content = `${GENERATED_TOC_HEADER}${yaml.dump(tocFromProject(project, path))}`;
   fs.writeFileSync(filename, content);

packages/myst-cli/src/project/toc.spec.ts

@@ -2,8 +2,8 @@ import { describe, expect, it, beforeEach, vi } from 'vitest';
 import memfs from 'memfs';
 import { Session } from '../session';
 import { projectFromPath } from './fromPath';
-import { pagesFromToc, projectFromToc } from './fromToc';
-import { tocFromProject } from './toToc';
+import { pagesFromTOC, projectFromTOC } from './fromTOC';
+import { tocFromProject } from './toTOC';
 import { findProjectsOnPath } from './load';
 
 vi.mock('fs', () => ({ ['default']: memfs.fs }));
@@ -636,7 +636,7 @@ describe('pagesFromToc', () => {
       'b.md': '',
       'c.md': '',
     });
-    expect(pagesFromToc(session, '.', 1)).toEqual([
+    expect(pagesFromTOC(session, '.', 1)).toEqual([
       { slug: 'index', file: 'index.md', level: 1 },
       { slug: 'a', file: 'a.md', level: 2 },
       { title: 'Sections', level: 2 },
@@ -652,7 +652,7 @@ describe('pagesFromToc', () => {
       'b.md': '',
       'c.md': '',
     });
-    expect(projectFromToc(session, '.', 1)).toEqual({
+    expect(projectFromTOC(session, '.', 1)).toEqual({
       index: 'index',
       file: 'index.md',
       path: '.',
@@ -672,7 +672,7 @@ describe('pagesFromToc', () => {
       'b.md': '',
       'c.md': '',
     });
-    expect(projectFromToc(session, '.', 0)).toEqual({
+    expect(projectFromTOC(session, '.', 0)).toEqual({
       index: 'index',
       file: 'index.md',
       path: '.',
@@ -692,7 +692,7 @@ describe('pagesFromToc', () => {
       'b.md': '',
       'c.md': '',
     });
-    expect(projectFromToc(session, '.', -1)).toEqual({
+    expect(projectFromTOC(session, '.', -1)).toEqual({
       index: 'index',
       file: 'index.md',
       path: '.',
@@ -714,7 +714,7 @@ describe('pagesFromToc', () => {
       'd.md': '',
       'e.md': '',
     });
-    expect(pagesFromToc(session, '.', 1)).toEqual([
+    expect(pagesFromTOC(session, '.', 1)).toEqual([
       { slug: 'index', file: 'index.md', level: 1 },
       { slug: 'a', file: 'a.md', level: 2 },
       { title: 'Sections', level: 2 },

packages/myst-cli/src/utils/toc.ts

@@ -10,7 +10,7 @@ import { addWarningForFile } from './addWarningForFile.js';
 export const TOC_FORMAT = 'jb-book';
 export const TOC_FORMAT_ARTICLE = 'jb-article';
 
-export type TocOptions = {
+export type TOCOptions = {
   path?: string;
   filename?: string;
   ci?: boolean;
@@ -43,9 +43,9 @@ export const tocFile = (filename: string): string => {
 };
 
 // See https://executablebooks.org/en/latest/blog/2021-06-18-update-toc/
-function upgradeOldJupyterBookToc(oldToc: any[]) {
+function upgradeOldJupyterBookTOC(oldTOC: any[]) {
   // TODO: numbering is ignored
-  const [root, ...parts] = oldToc;
+  const [root, ...parts] = oldTOC;
   const toc: TOC = {
     root: root.file,
     format: TOC_FORMAT,
@@ -57,12 +57,12 @@ function upgradeOldJupyterBookToc(oldToc: any[]) {
   return toc;
 }
 
-export function readTOC(log: Logger, opts?: TocOptions): TOC {
+export function readTOC(log: Logger, opts?: TOCOptions): TOC {
   const filename = join(opts?.path || '.', opts?.filename || '_toc.yml');
   const toc = yaml.load(fs.readFileSync(filename).toString()) as any;
   if (Array.isArray(toc)) {
     try {
-      const old = upgradeOldJupyterBookToc(toc);
+      const old = upgradeOldJupyterBookTOC(toc);
       log.warn(
         `${filename} is out of date: see https://executablebooks.org/en/latest/blog/2021-06-18-update-toc`,
       );
@@ -98,7 +98,7 @@ export function validateTOC(session: ISession, path: string): boolean {
       filename,
       `Table of Contents (ToC) file did not pass validation:\n - ${message}\n - An implicit ToC will be used instead\n`,
       'error',
-      { ruleId: RuleId.validTocStructure },
+      { ruleId: RuleId.validTOCStructure },
     );
     return false;
   }

packages/myst-common/src/ruleids.ts

@@ -38,8 +38,8 @@ export enum RuleId {
   roleBodyCorrect = 'role-body-correct',
   // Project structure rules
   tocContentsExist = 'toc-contents-exist',
-  validTocStructure = 'valid-toc-structure',
-  validToc = 'valid-toc',
+  validTOCStructure = 'valid-toc-structure',
+  validTOC = 'valid-toc',
   tocWritten = 'toc-written',
   // Image rules
   imageDownloads = 'image-downloads',

packages/mystmd/src/init.ts

@@ -4,7 +4,7 @@ import { Session, init, makeSiteOption } from 'myst-cli';
 import { clirun } from './clirun.js';
 import {
   makeProjectOption,
-  makeWriteTocOption,
+  makeWriteTOCOption,
   makeGithubPagesOption,
   makeGithubCurvenoteOption,
 } from './options.js';
@@ -14,7 +14,7 @@ export function makeInitCLI(program: Command) {
     .description('Initialize a MyST project in the current directory')
     .addOption(makeProjectOption('Initialize config for MyST project content'))
     .addOption(makeSiteOption('Initialize config for MyST site'))
-    .addOption(makeWriteTocOption())
+    .addOption(makeWriteTOCOption())
     .addOption(makeGithubPagesOption())
     .addOption(makeGithubCurvenoteOption())
     .action(clirun(Session, init, program));

packages/mystmd/src/options.ts

@@ -4,7 +4,7 @@ export function makeProjectOption(description: string) {
   return new Option('--project', description).default(false);
 }
 
-export function makeWriteTocOption() {
+export function makeWriteTOCOption() {
   return new Option(
     '--write-toc',
     'Generate editable _toc.yml file for project if it does not exist',