Move titles of tutorials into the YAML header and add short_title for…

… the sidebar (#1981) * rename yaml header field title into short_title * Copy the markdown level 1 titles (#) into a new Yaml header field title * Change src/ocamlorg_frontend/pages/tutorial.eml file to render the title of the tutorial at the beginning of each tutorial * Remove the markdown level 1 (#) titles from the markdown files * Remove debugging text * use Utils.slugify instead of defining a function that does the same thing * rename short_title from Sets to set * rename title from Preprocessors to title: Preprocessors and PPXs * Update data/tutorials/language/0it_05_imperative.md * Update src/ocamlorg_frontend/pages/tutorial.eml Co-authored-by: Cuihtlauac Alvarado <[email protected]> * Update src/ocamlorg_frontend/pages/tutorial.eml Co-authored-by: Cuihtlauac Alvarado <[email protected]> * replace tutorial.title with tutorial.short_title --------- Co-authored-by: Cuihtlauac Alvarado <[email protected]>
ocaml · Jan 26, 2024 · 3e267b3 · 3e267b3
1 parent 623ae7a
commit 3e267b3
Show file tree

Hide file tree

Showing 65 changed files with 83 additions and 135 deletions.
diff --git a/data/tutorials/getting-started/1_00_install_OCaml.md b/data/tutorials/getting-started/1_00_install_OCaml.md
@@ -1,14 +1,13 @@
 ---
 id: installing-ocaml
 title: Installing OCaml
+short_title: Installing OCaml
 description: |
   This page will help you install OCaml and the OCaml Platform Tools. |
   These instructions work on Windows, and Unix systems like Linux, and macOS.
 category: "First Steps"
 ---
 
-# Installing OCaml
-
 This guide will walk you through a minimum installation of OCaml. That includes installing a package manager and [the compiler](#installation-on-unix-and-macos) itself. We'll also install some platform tools like a build system, support for your editor, and a few other important ones.
 
 On this page, you'll find installation instructions for Linux, macOS, and &ast;BSD for recent OCaml versions. For Docker, Linux instructions apply, except when setting up opam. For Windows, we recommend using WSL but also provide instructions for installing OCaml 4.14.0 via the [Diskuv OCaml](https://github.com/diskuv/dkml-installer-ocaml#readme) Installer. If you are setting up OCaml on Windows and are unsure which installation method to use, you might be interested in reading [OCaml on Windows](/docs/ocaml-on-windows) first.

diff --git a/data/tutorials/getting-started/1_01_a_tour_of_ocaml.md b/data/tutorials/getting-started/1_01_a_tour_of_ocaml.md
@@ -1,6 +1,7 @@
 ---
 id: tour-of-ocaml
 title: A Tour of OCaml
+short_title: A Tour of OCaml
 description: >
   Hop on the OCaml sightseeing bus. This absolute beginner tutorial will drive you through the marvels and wonders of OCaml. We'll have a look at the most commonly used language features.
 category: "First Steps"
@@ -11,8 +12,6 @@ recommended_next_tutorials:
   - "lists"
 ---
 
-# A Tour of OCaml
-
 Before proceeding with this tutorial, please ensure you've installed OCaml and set up the environment, as described on the [install OCaml](/docs/installing-ocaml) page. After we take an introductory tour of OCaml's language features, we'll proceed to create our first OCaml project in the [Your First OCaml Program](/docs/your-first-program) tutorial.
 
 You need to have OCaml installed. No OCaml or functional programming knowledge is required; however, it is assumed the reader has some basic software development knowledge. This tutorial is probably not adapted to learn programming.

diff --git a/data/tutorials/getting-started/1_02_your_first_ocaml_program.md b/data/tutorials/getting-started/1_02_your_first_ocaml_program.md
@@ -1,6 +1,7 @@
 ---
 id: your-first-program
 title: Your First OCaml Program
+short_title: Your First OCaml Program
 description: >
   Learn how to write your very first OCaml program.
 category: "First Steps"
@@ -11,8 +12,6 @@ recommended_next_tutorials:
   - "lists"
 ---
 
-# Your First OCaml Program
-
 To complete this tutorial, you need to have [installed OCaml](/install). Optionally, we recommend [configuring your editor](/docs/set-up-editor).
 
 We will work with files containing OCaml source code and compile them to produce executable binaries. However, this is not a detailed tutorial on OCaml compilation, project modularisation, or dependencies management; it only gives a glimpse at those topics. The goal is to sketch the bigger picture in order to avoid getting lost in the details. In other words, we do breadth-first learning instead of depth-first learning.

diff --git a/data/tutorials/getting-started/2_00_editor_setup.md b/data/tutorials/getting-started/2_00_editor_setup.md
@@ -1,13 +1,12 @@
 ---
 id: set-up-editor
 title: Configuring Your Editor
+short_title: Configuring Your Editor
 description: |
   This page will show you how to set up your editor for OCaml. 
 category: "Tooling"
 ---
 
-# Configuring Your Editor
-
 While the toplevel is great for interactively trying out the language, we will shortly need to write OCaml files in an editor. We already installed the tools required to enhance Merlin, our editor of choice with OCaml support. Merlin provides all features such as "jump to definition," "show type," and `ocaml-lsp-server`, a server delivers those features to the editor through the LSP server.
 
 OCaml has plugins for many editors, but the most actively maintained are for Visual Studio Code, Emacs, and Vim.

diff --git a/data/tutorials/getting-started/2_01_toplevel.md b/data/tutorials/getting-started/2_01_toplevel.md
@@ -1,13 +1,12 @@
 ---
 id: toplevel-introduction
 title: Introduction to the OCaml Toplevel
+short_title: Introduction to the OCaml Toplevel
 description: |
   This page will give you a brief introduction to the OCaml toplevel.
 category: "Tooling"
 ---
 
-# Introduction to the OCaml Toplevel
-
 An OCaml toplevel is a chat between the user and OCaml. The user writes OCaml code, and UTop evaluates it. This is why it is also called a Read-Eval-Print-Loop (REPL). Several OCaml toplevels exist, like `ocaml` and `utop`. We recommend using UTop, which is part of the [OCaml Platform](/docs/platform) toolchain. 
 
 To run UTop, we use the `utop` command, which looks like this:

diff --git a/data/tutorials/getting-started/2_02_opam_switch.md b/data/tutorials/getting-started/2_02_opam_switch.md
@@ -1,13 +1,12 @@
 ---
 id: opam-switch-introduction
 title: Introduction to opam Switches
+short_title: Introduction to opam Switches
 description: |
   This page will give you a brief introduction to opam switches, what they're used for, and how to create them.
 category: "Tooling"
 ---
 
-# Introduction to opam Switches
-
 OCaml's package manager, opam, introduces the concept of a _switch_, which is an isolated OCaml environment. These switches often cause confusion amongst OCaml newcomers, so this document aims to provide a better understanding of opam switches and their usage for managing dependencies and project-specific configurations. 
 
 Opam is designed to manage multiple concurrent installation prefixes called "switches." Similar to Python's `virtualenv`, an opam switch is a tool that creates isolated environments. They are independent of each other and have their own set of installed packages, repositories, and configuration options. Switches also have their own OCaml compiler, libraries, and binaries. This enables you to have multiple compiler versions available at once.

diff --git a/data/tutorials/getting-started/3_01_ocaml_on_windows.md b/data/tutorials/getting-started/3_01_ocaml_on_windows.md
@@ -1,13 +1,12 @@
 ---
 id: ocaml-on-windows
 title: OCaml on Windows
+short_title: OCaml on Windows
 description: >
   Read about the state of OCaml on Windows and our roadmap to improve Windows support.
 category: "Resources"
 ---
 
-# OCaml on Windows
-
 There is a new [Diskuv OCaml][DKML] ("DKML") Windows
 installer that we recommend for new users. However, while [Diskuv OCaml][DKML] has a modern OCaml 4.14.0 compiler,
 it does not track the latest OCaml compilers. We will officially support Windows as a Tier 1

diff --git a/data/tutorials/getting-started/3_02_arm_fix.md b/data/tutorials/getting-started/3_02_arm_fix.md
@@ -1,13 +1,12 @@
 ---
 id: arm64-fix
 title: Fix Homebrew Errors on Apple M1
+short_title: Fix Homebrew Errors on Apple M1
 description: |
   This page will walk you through the workaround for ARM64 processors on newer Macs.
 category: "Resources"
 ---
 
-# Fix Homebrew Errors on Apple M1
-
 Since [Homebrew has changed](https://github.com/Homebrew/brew/issues/9177) the way it installs, sometimes the executable files cannot be found on macOS ARM64 M1. This might cause errors as you work through these tutorials. We want Homebrew to install ARM64 by default, so there are a few changes we need to make in order to do this.
 
 Before we get started, let's check where Homebrew is installed. We can do this by running this in the CLI:

diff --git a/data/tutorials/getting-started/3_03_ocaml_playground.md b/data/tutorials/getting-started/3_03_ocaml_playground.md
@@ -1,15 +1,14 @@
 ---
 id: ocaml-playground
-title: The OCaml Playground
+title: Using the OCaml Playground
+short_title: The OCaml Playground
 description: |
   This page will walk you through the OCaml Playground
 category: "Resources"
 ---
 
 Welcome to OCaml's in-browser playground! 
 
-# Using the OCaml Playground
-
 The [OCaml Playground](https://ocaml.org/play) is made to make it easier for users, especially beginners, to get started with OCaml without worrying about installing anything. Everything is ready to use once you open it.
 
 It has a simple interface of two panels: the _editor panel_ on the left and the _output panel_ on the right.

diff --git a/data/tutorials/guides/0tt_00_formatting_text.md b/data/tutorials/guides/0tt_00_formatting_text.md
@@ -1,15 +1,14 @@
 ---
 id: formatting-text
 title: Formatting and Wrapping Text
+short_title: Formatting and Wrapping Text
 description: >
   The Format module of Caml Light and OCaml's standard libraries
   provides pretty-printing facilities to get a fancy display for printing
   routines
 category: "Tutorials"
 ---
 
-# Formatting and Wrapping Text
-
 The `Format` module of Caml Light and OCaml's standard libraries
 provides pretty-printing facilities to get a fancy display for printing
 routines. This module implements a “pretty-printing engine” that is

diff --git a/data/tutorials/guides/0tt_01_command_line_arguments.md b/data/tutorials/guides/0tt_01_command_line_arguments.md
@@ -1,13 +1,12 @@
 ---
 id: cli-arguments
 title: Command-line Arguments
+short_title: Command-line Arguments
 description: >
   The Arg module that comes with the compiler can help you write command line interfaces
 category: "Tutorials"
 ---
 
-# Command-line Arguments
-
 In this tutorial we learn how to read command line arguments directly, using
 OCaml's `Sys.argv` array, and then how to do so more easily using the standard
 library's `Arg` module.

diff --git a/data/tutorials/guides/0tt_02_file_manipulation.md b/data/tutorials/guides/0tt_02_file_manipulation.md
@@ -1,13 +1,12 @@
 ---
 id: file-manipulation
 title: File Manipulation
+short_title: File Manipulation
 description: >
   A guide to basic file manipulation in OCaml with the standard library
 category: "Tutorials"
 ---
 
-# File Manipulation
-
 This is a guide to basic file manipulation in OCaml using only the
 standard library.
 

diff --git a/data/tutorials/guides/0tt_03_calling_c_libraries.md b/data/tutorials/guides/0tt_03_calling_c_libraries.md
@@ -1,13 +1,12 @@
 ---
 id: calling-c-libraries
 title: Calling C Libraries
+short_title: Calling C Libraries
 description: >
   Cross the divide and call C code from your OCaml program
 category: "Tutorials"
 ---
 
-# Calling C Libraries
-
 ## MiniGtk
 While the structure of lablgtk outlined in [Introduction to
 Gtk](https://v2.ocaml.org/learn/tutorials/introduction_to_gtk.html) seems perhaps

diff --git a/data/tutorials/guides/0tt_04_calling_fortran_libraries.md b/data/tutorials/guides/0tt_04_calling_fortran_libraries.md
@@ -1,13 +1,12 @@
 ---
 id: calling-fortran-libraries
 title: Calling Fortran Libraries
+short_title: Calling Fortran Libraries
 description: >
   Cross the divide and call Fortran code from your OCaml program
 category: "Tutorials"
 ---
 
-# Calling Fortran Libraries
-
 Fortran isn't a language the many people write new code in but it still
 is in extensive use in the scientific communities. Many, many libraries
 exist for doing numerical calculation that will never be written in C or

diff --git a/data/tutorials/guides/1wf_00_compiling_ocaml_projects.md b/data/tutorials/guides/1wf_00_compiling_ocaml_projects.md
@@ -1,13 +1,12 @@
 ---
 id: compiling-ocaml-projects
 title: Compiling OCaml Projects
+short_title: Compiling OCaml Projects
 description: >
   An introduction to the OCaml compiler tools for building OCaml projects as well as the most common build tools
 category: "Guides"
 ---
 
-# Compiling OCaml Projects
-
 This tutorial explains how to compile your OCaml programs into executable form.
 It addresses, in turn:
 

diff --git a/data/tutorials/guides/1wf_01_debugging.md b/data/tutorials/guides/1wf_01_debugging.md
@@ -1,13 +1,12 @@
 ---
 id: debugging
 title: Debugging
+short_title: Debugging
 description: >
   Learn to debug OCaml programs using tracing and ocamldebug
 category: "Guides"
 ---
 
-# Debugging
-
 This tutorial presents four techniques for debugging OCaml programs:
 
 * [Tracing functions calls](#tracing-functions-calls-in-the-toplevel),

diff --git a/data/tutorials/guides/1wf_02_error_handling.md b/data/tutorials/guides/1wf_02_error_handling.md
@@ -1,13 +1,12 @@
 ---
 id: error-handling
 title: Error Handling
+short_title: Error Handling
 description: >
   Discover the different ways you can manage errors in your OCaml programs
 category: "Guides"
 ---
 
-# Error Handling
-
 In OCaml, errors can be handled in several ways. This document presents most of
 the available means. However, handling errors using the effect handlers
 introduced in OCaml 5 hasn't been addressed yet. This topic is also addressed in the

diff --git a/data/tutorials/guides/1wf_03_profiling.md b/data/tutorials/guides/1wf_03_profiling.md
@@ -1,13 +1,12 @@
 ---
 id: profiling
 title: Profiling
+short_title: Profiling
 description: >
   Understand how to profile your OCaml code to analyse its performance and produce faster programs
 category: "Guides"
 ---
 
-# Profiling
-
 ## Speed
 Why is OCaml fast? Indeed, step back and ask *is OCaml fast?* How can we
 make programs faster? In this chapter we'll look at what actually

diff --git a/data/tutorials/guides/1wf_04_multicore_ready.md b/data/tutorials/guides/1wf_04_multicore_ready.md
@@ -1,14 +1,12 @@
 ---
 id: multicore-transition
-title: Transitioning to Multicore with TSan
+title: Transitioning to Multicore with ThreadSanitizer
+short_title: Transitioning to Multicore with TSan
 description: >
   Learn to make your OCaml code multicore ready with ThreadSanitizer
 category: "Guides"
 ---
 
-
-# Transitioning to Multicore with ThreadSanitizer
-
 The 5.0 release brought Multicore, `Domain`-based parallelism to the
 OCaml language. Parallel `Domain`s performing uncoordinated operations
 on shared mutable memory locations may however cause data races. Such

diff --git a/data/tutorials/guides/1wf_05_garbage_collection.md b/data/tutorials/guides/1wf_05_garbage_collection.md
@@ -1,13 +1,12 @@
 ---
 id: garbage-collection
 title: How to Work with the Garbage Collector
+short_title: How to Work with the Garbage Collector
 description: >
   How to use the Gc module in OCaml and how to write your own finalisers.
 category: "Guides"
 ---
 
-# How to Work with the Garbage Collector
-
 In [Understanding the Garbage Collector](/docs/garbage-collector), discussed how Garbage Collection in OCaml works.
 In this tutorial, we look at how to use the `Gc` module and how to write your own finalisers.
 At the end of the tutorial, we give some exercises you might try in order to develop a better understanding.

diff --git a/data/tutorials/guides/rs_00_guidelines.md b/data/tutorials/guides/rs_00_guidelines.md
@@ -1,13 +1,12 @@
 ---
 id: guidelines
 title: OCaml Programming Guidelines
+short_title: OCaml Programming Guidelines
 description: >
   Opinionated guidelines for writing OCaml code
 category: "Resources"
 ---
 
-# OCaml Programming Guidelines
-
 This is a set of reasonable guidelines for writing OCaml
 programs that reflect the consensus among veteran OCaml
 programmers.

diff --git a/data/tutorials/guides/rs_01_common_error_messages.md b/data/tutorials/guides/rs_01_common_error_messages.md
@@ -1,13 +1,12 @@
 ---
 id: common-errors
 title: Common Error Messages
+short_title: Common Error Messages
 description: >
   Understand the most common error messages the OCaml compiler can throw at you
 category: "Resources"
 ---
 
-# Common Error Messages
-
 This page gives a list of quick explanations for some error or warning
 messages that are emitted by the OCaml compilers. Longer explanations
 are usually given in dedicated sections of this tutorial.

diff --git a/data/tutorials/guides/rs_02_comparison_of_standard_containers.md b/data/tutorials/guides/rs_02_comparison_of_standard_containers.md
@@ -1,12 +1,12 @@
 ---
 id: data-structures-comparison 
 title: Comparison of Standard Containers
+short_title: Comparison of Standard Containers
 description: >
   Rough comparison of the different container types in OCaml
 category: "Resources"
 ---
 
-# Comparison of Standard Containers
 This is a rough comparison of the different container types 
 provided by the OCaml standard library. In each
 case, _n_ is the number of valid elements in the container.

diff --git a/data/tutorials/language/0it_00_values_functions.md b/data/tutorials/language/0it_00_values_functions.md
@@ -1,13 +1,12 @@
 ---
 id: values-and-functions
 title: Values and Functions
+short_title: Values and Functions
 description: |
   Functions, values, definitions, environments, scopes, closures, and shadowing. This tutorial will help you master the fundamentals.
 category: "Introduction"
 ---
 
-# Values and Functions
-
 ## Introduction
 
 In OCaml, functions are treated as values, so you can use functions as arguments to functions and return them from functions. This tutorial introduces the relationship between expressions, values, and names. The first four sections address non-function values. The following sections, starting at [Function as Values](#function-as-values), address functions.

diff --git a/data/tutorials/language/0it_01_basic_datatypes.md b/data/tutorials/language/0it_01_basic_datatypes.md
@@ -1,13 +1,12 @@
 ---
 id: basic-data-types
 title: Basic Data Types and Pattern Matching
+short_title: Basic Data Types and Pattern Matching
 description: |
   Predefined Types, Variants, Records, and Pattern Matching
 category: "Introduction"
 ---
 
-# Basic Data Types And Pattern Matching
-
 ## Introduction
 
 This document covers atomic types, such as integers and Booleans; predefined compound types, like strings and lists; and user-defined types, namely variants and records. We show how to pattern matching on those types.