Fixed broken links

Author: dbaileychess

docs-old/source/Building.md

@@ -72,6 +72,7 @@ We generate [SLSA3 signatures](slsa.dev) using the OpenSSF's [slsa-framework/sls
 ```shell
 $ slsa-verifier -artifact-path <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
   PASSED: Verified SLSA provenance
+```
 
 ## Building for Android
 

docs/source/annotation.md

@@ -28,15 +28,12 @@ cd tests/annotated_binary
 
 Which will produce a `annotated_binary.afb` file in the current directory.
 
+The `annotated_binary.bin` is the flatbufer binary of the data contained within
+`annotated_binary.json`, which was made by the following command:
 
-!!! Tip
-    
-    The `annotated_binary.bin` is the flatbufer binary of the data contained
-    within `annotated_binary.json`, which was made by the following command:
-
-    ```sh
-    ..\..\flatc -b annotated_binary.fbs annotated_binary.json
-    ```
+```sh
+..\..\flatc -b annotated_binary.fbs annotated_binary.json
+```
 
 ## .afb Text Format
 

docs/source/building.md

@@ -16,11 +16,9 @@ Use `cmake` to configure a project based on your environment and platform.
     cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
     ```
 
-    !!! note
-
-        To use `clang` instead of `gcc` you may need to set prepend some
-        environment variables e.g. `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake
-        -G "Unix MakeFiles"`
+To use `clang` instead of `gcc` you may need to set prepend some environment
+variables e.g. `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix
+MakeFiles"`
 
 === "Windows"
 
@@ -78,3 +76,88 @@ Once the project files are generated, build as normal for your platform.
 ## Building with Bazel
 
 ## Building with VCPKG
+
+You can download and install flatbuffers using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
+
+    git clone https://github.com/Microsoft/vcpkg.git
+    cd vcpkg
+    ./bootstrap-vcpkg.sh
+    ./vcpkg integrate install
+    ./vcpkg install flatbuffers
+
+The flatbuffers port in vcpkg is kept up to date by Microsoft team members and community contributors.
+If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
+
+
+
+## Building for Android
+
+There is a `flatbuffers/android` directory that contains all you need to build
+the test executable on android (use the included `build_apk.sh` script, or use
+`ndk_build` / `adb` etc. as usual). Upon running, it will output to the log
+if tests succeeded or not.
+
+You may also run an android sample from inside the `flatbuffers/samples`, by
+running the `android_sample.sh` script. Optionally, you may go to the
+`flatbuffers/samples/android` folder and build the sample with the
+`build_apk.sh` script or `ndk_build` / `adb` etc.
+
+## Using FlatBuffers in your own projects
+
+For C++, there is usually no runtime to compile, as the code consists of a
+single header, `include/flatbuffers/flatbuffers.h`. You should add the
+`include` folder to your include paths. If you wish to be
+able to load schemas and/or parse text into binary buffers at runtime,
+you additionally need the other headers in `include/flatbuffers`. You must
+also compile/link `src/idl_parser.cpp` (and `src/idl_gen_text.cpp` if you
+also want to be able convert binary to text).
+
+To see how to include FlatBuffers in any of our supported languages, please
+view the [Tutorial](tutorial.md) and select your appropriate
+language using the radio buttons.
+
+### Using in CMake-based projects
+If you want to use FlatBuffers in a project which already uses CMake, then a more
+robust and flexible approach is to build FlatBuffers as part of that project directly.
+This is done by making the FlatBuffers source code available to the main build
+and adding it using CMake's `add_subdirectory()` command. This has the
+significant advantage that the same compiler and linker settings are used
+between FlatBuffers and the rest of your project, so issues associated with using
+incompatible libraries (eg debug/release), etc. are avoided. This is
+particularly useful on Windows.
+
+Suppose you put FlatBuffers source code in directory `${FLATBUFFERS_SRC_DIR}`.
+To build it as part of your project, add following code to your `CMakeLists.txt` file:
+```cmake
+# Add FlatBuffers directly to our build. This defines the `flatbuffers` target.
+add_subdirectory(${FLATBUFFERS_SRC_DIR}
+                 ${CMAKE_CURRENT_BINARY_DIR}/flatbuffers-build
+                 EXCLUDE_FROM_ALL)
+
+# Now simply link against flatbuffers as needed to your already declared target.
+# The flatbuffers target carry header search path automatically if CMake > 2.8.11.
+target_link_libraries(own_project_target PRIVATE flatbuffers)
+```
+When build your project the `flatbuffers` library will be compiled and linked 
+to a target as part of your project.
+
+#### Override default depth limit of nested objects
+To override [the depth limit of recursion](languages/cpp.md), 
+add this directive:
+```cmake
+set(FLATBUFFERS_MAX_PARSING_DEPTH 16)
+```
+to `CMakeLists.txt` file before `add_subdirectory(${FLATBUFFERS_SRC_DIR})` line.
+
+## Downloading binaries
+You can download the binaries from the
+[GitHub release page](https://github.com/google/flatbuffers/releases).
+
+We generate [SLSA3 signatures](http://slsa.dev) using the OpenSSF's [slsa-framework/slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator). To verify the binaries:
+1. Install the verification tool from [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation)
+1. Download the file named `attestation.intoto.jsonl` from the GitHub release
+1. Run:
+```shell
+$ slsa-verifier -artifact-path <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
+  PASSED: Verified SLSA provenance
+```

docs/source/evolution.md

@@ -20,9 +20,8 @@ of the added field if accessed).
 
 Older code will simply ignore the new field in the flatbuffer.
 
-!!! tip "Use `id` attributes"
-
-     You can ignore this rule if you use the `id` attribute on all the fields of a table.
+You can ignore this rule if you use the `id` attribute on all the fields of a
+table.
 
 ### Removal
 

docs/source/flexbuffers.md

@@ -163,7 +163,7 @@ map.get("unknown").isNull();  // true
 # Binary encoding
 
 A description of how FlexBuffers are encoded is in the
-[internals](@ref flatbuffers_internals) document.
+[internals](internals.md) document.
 
 
 # Nesting inside a FlatBuffer

docs/source/internals.md

@@ -316,7 +316,7 @@ that may further help clarify the format.
 
 # FlexBuffers
 
-The [schema-less](@ref flexbuffers) version of FlatBuffers have their
+The [schema-less](flexbuffers.md) version of FlatBuffers have their
 own encoding, detailed here.
 
 It shares many properties mentioned above, in that all data is accessed

docs/source/languages/c.md

@@ -12,7 +12,7 @@ project.
 
 ## General Documention
 
-- [Tutorial](@ref flatbuffers_guide_tutorial) - select C as language
+- [Tutorial](../tutorial.md) - select C as language
   when scrolling down
 - [FlatCC Guide](https://github.com/dvidelabs/flatcc#flatcc-flatbuffers-in-c-for-c)
 - [The C Builder Interface](https://github.com/dvidelabs/flatcc/blob/master/doc/builder.md#the-builder-interface)

docs/source/languages/c_sharp.md

@@ -4,15 +4,15 @@ Use in C\#    {#flatbuffers_guide_use_c-sharp}
 ## Before you get started
 
 Before diving into the FlatBuffers usage in C#, it should be noted that
-the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
+the [Tutorial](../tutorial.md) page has a complete guide to
 general FlatBuffers usage in all of the supported languages (including C#).
 This page is designed to cover the nuances of FlatBuffers usage,
 specific to C#.
 
-You should also have read the [Building](@ref flatbuffers_guide_building)
+You should also have read the [Building](../building.md)
 documentation to build `flatc` and should be familiar with
-[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
-[Writing a schema](@ref flatbuffers_guide_writing_schema).
+[Using the schema compiler](../flatc.md) and
+[Writing a schema](../schema.md).
 
 ## FlatBuffers C# code location
 
@@ -62,7 +62,7 @@ by running the following commands from inside the `FlatBuffers.Test` folder:
 
 ## Using the FlatBuffers C# library
 
-*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
+*Note: See [Tutorial](../tutorial.md) for a more in-depth
 example of how to use FlatBuffers in C#.*
 
 FlatBuffers supports reading and writing binary FlatBuffers in C#.
@@ -141,7 +141,7 @@ To use it:
 
 ## Buffer verification
 
-As mentioned in [C++ Usage](@ref flatbuffers_guide_use_cpp) buffer
+As mentioned in [C++ Usage](cpp.md) buffer
 accessor functions do not verify buffer offsets at run-time.
 If it is necessary, you can optionally use a buffer verifier before you
 access the data. This verifier will check all offsets, all sizes of

docs/source/languages/cpp.md

@@ -3,7 +3,7 @@
 ## Before you get started
 
 Before diving into the FlatBuffers usage in C++, it should be noted that
-the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
+the [Tutorial](../tutorial.md) page has a complete guide
 to general FlatBuffers usage in all of the supported languages (including C++).
 This page is designed to cover the nuances of FlatBuffers usage, specific to
 C++.
@@ -12,8 +12,8 @@ C++.
 
 This page assumes you have written a FlatBuffers schema and compiled it
 with the Schema Compiler. If you have not, please see
-[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler)
-and [Writing a schema](@ref flatbuffers_guide_writing_schema).
+[Using the schema compiler](../flatc.md)
+and [Writing a schema](../schema.md).
 
 Assuming you wrote a schema, say `mygame.fbs` (though the extension doesn't
 matter), you've generated a C++ header called `mygame_generated.h` using the
@@ -34,15 +34,15 @@ The test code itself is located in
 [test.cpp](https://github.com/google/flatbuffers/blob/master/tests/test.cpp).
 
 This test file is built alongside `flatc`. To review how to build the project,
-please read the [Building](@ref flatbuffers_guide_building) documentation.
+please read the [Building](../building.md) documentation.
 
 To run the tests, execute `flattests` from the root `flatbuffers/` directory.
 For example, on [Linux](https://en.wikipedia.org/wiki/Linux), you would simply
 run: `./flattests`.
 
 ## Using the FlatBuffers C++ library
 
-*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
+*Note: See [Tutorial](../tutorial.md) for a more in-depth
 example of how to use FlatBuffers in C++.*
 
 FlatBuffers supports both reading and writing FlatBuffers in C++.
@@ -261,7 +261,7 @@ using hashes which are then represented as typed pointers in the object API.
 
 To make this work have a field in the objects you want to referred to which is
 using the string hashing feature (see `hash` attribute in the
-[schema](@ref flatbuffers_guide_writing_schema) documentation). Then you have
+[schema](../schema.md) documentation). Then you have
 a similar hash in the field referring to it, along with a `cpp_type`
 attribute specifying the C++ type this will refer to (this can be any C++
 type, and will get a `*` added).
@@ -555,11 +555,11 @@ recursion depth. Number of nested declarations in a schema or number of
 nested json-objects is limited. By default, this depth limit set to `64`.
 It is possible to override this limit with `FLATBUFFERS_MAX_PARSING_DEPTH`
 definition. This definition can be helpful for testing purposes or embedded
-applications. For details see [build](@ref flatbuffers_guide_building) of
+applications. For details see [build](../building.md) of
 CMake-based projects.
 
 ## Dependence from C-locale {#flatbuffers_locale_cpp}
-The Flatbuffers [grammar](@ref flatbuffers grammar) uses ASCII
+The Flatbuffers [grammar](../grammar.md) uses ASCII
 character set for identifiers, alphanumeric literals, reserved words.
 
 Internal implementation of the Flatbuffers depends from functions which
@@ -602,7 +602,7 @@ compatible with the `IEEE-754` floating-point standard.
 The schema and json parser may fail if `fast-math` or `/fp:fast` mode is active.
 
 ### Support of hexadecimal and special floating-point numbers
-According to the [grammar](@ref flatbuffers_grammar) `fbs` and `json` files
+According to the [grammar](../grammar.md) `fbs` and `json` files
 may use hexadecimal and special (`NaN`, `Inf`) floating-point literals.
 The Flatbuffers uses `strtof` and `strtod` functions to parse floating-point
 literals. The Flatbuffers library has a code to detect a compiler compatibility
@@ -625,7 +625,7 @@ According to the `IEEE-754`, a comparison with `NaN` always returns
 an unordered result even when compared with itself. As a result, a whole
 Flatbuffers object will be not equal to itself if has one or more `NaN`.
 Flatbuffers scalar fields that have the default value are not actually stored
-in the serialized data but are generated in code (see [Writing a schema](@ref flatbuffers_guide_writing_schema)).
+in the serialized data but are generated in code (see [Writing a schema](../schema.md)).
 Scalar fields with `NaN` defaults break this behavior.
 If a schema has a lot of `NaN` defaults the Flatbuffers can override
 the unordered comparison by the ordered: `(NaN==NaN)->true`.

docs/source/languages/dart.md

@@ -4,15 +4,15 @@ Use in Dart    {#flatbuffers_guide_use_dart}
 ## Before you get started
 
 Before diving into the FlatBuffers usage in Dart, it should be noted that
-the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
+the [Tutorial](../tutorial.md) page has a complete guide
 to general FlatBuffers usage in all of the supported languages (including Dart).
 This page is designed to cover the nuances of FlatBuffers usage, specific to
 Dart.
 
-You should also have read the [Building](@ref flatbuffers_guide_building)
+You should also have read the [Building](../building.md)
 documentation to build `flatc` and should be familiar with
-[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
-[Writing a schema](@ref flatbuffers_guide_writing_schema).
+[Using the schema compiler](../flatc.md) and
+[Writing a schema](../schema.md).
 
 ## FlatBuffers Dart library code location
 
@@ -34,7 +34,7 @@ to be installed.*
 
 ## Using the FlatBuffers Dart library
 
-*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
+*Note: See [Tutorial](../tutorial.md) for a more in-depth
 example of how to use FlatBuffers in Dart.*
 
 FlatBuffers supports reading and writing binary FlatBuffers in Dart.