This repository serves as the developer hub SANDBOX for the Substrate blockchain framework. The docs are written in pure markdown, processed by MKdocs.

The ./old-docs-migration folder has all the ported docs, renamed for convenience to be .md files via this method.

Now our mission, if we choose to accept it... (we do!), is to port all the files in ./old-docs-migration into the new framework outlined in our team Notion:

• Notion Documentation Plan.

The framework will be implemented in the ./source/docs folder.

1. Select a new page you want to write, and mark yourself as managing this in the tracker spreadsheet
2. Make a new file in the /source/docs dir for this work or drag a page from ./old-docs-migration into the right place in the /source/docs dir.
3. Cut the contents of any file that you are migrating from ./old-docs-migration into the /source/docs files so that it no longer remains in the ./old-docs-migration files.
4. Delete any duplicated content in ./old-docs-migration you run into while pulling from multiple locations.
5. Selectively reword as needed existing content in /source/docs when you find it already in place in ./old-docs-migration. The *delete it from ./old-docs-migration.

This way our definition of done with the migration is when ./old-docs-migration is empty!

1. Clone the repo

   # create a new folder to get going
   git clone [email protected]:substrate-developer-hub/docs-sandbox.git

2. Install mkdocs

   https://www.mkdocs.org/getting-started/

3. Serve the site

   # move to the source dir that includes `mkdocs.yml`
   cd docs-sandbox/source
   # options for `--theme [mkdocs|material|readthedocs]`
   mkdocs serve

   The site should be ready to view at http://127.0.0.1:8000/ and/or http://localhost:8000/

4. Make edits...

5. Update source/mkdocs.yml to render site

   Should be relatively self explanatory

   # Navigation
   nav:
     - 'Some section':
       - 'Page Title': 'some/path/to-a-file.md'
       - 'Subsection':
         - 'some/path/to-a-file.md

6. See they changes look nice and there are no mkdocs serve warnings/errors...

7. Commit changes...

8. Make a PR...

9. Deploy to gh-pages

   mkdocs gh-deploy

10. Profit 😎

TBD

To migrate old v3 dir dumped into old-docs-migration

To get old dir <folder>/index.mdx to <folder>.md:

# move all `<folder>/index.mdx` to `<folder>.md`
find ./ -depth -name "*.mdx" -exec sh -c 'mv $1 "${1%/index.mdx}.md"' _ {} \;
# delete all empty folders
find /path/ -empty -type d -delete