Skip to content

polkadot-developers/docs-sandbox

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 

Repository files navigation

Substrate Developer Hub SANDBOX


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

🦾 Docs Migration Instructions:

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:

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

📑 Workflow

  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!

🚀 Quick start

  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 😎

License

TBD


bash file migration magic

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

Releases

No releases published

Packages

No packages published

Languages